A <:define> can already carry a JSDoc-style comment beside a parameter, and nothing surfaces it:
<:define tag="my-box:div"
/** How wide the box is. Any CSS length. */
::width=${'10rem'}
style="width: ${width}"
><:slot /></:define>This compiles today. The comment parses, is stripped, and does not reach the output — so this is entirely an extension-side feature, with no compiler change needed.
What it should do
Hovering ::width at a usage site, and completing it, should show "How wide the box is. Any CSS length."
Where it lands
src/hovers.ts — findHover() resolves a declaration and renders the declaring line.src/completions.ts — parameter items already carry a detail taken from the declaration's source location.
Both already find the declaration; neither looks at what sits above it.
The design point worth keeping
hovers.ts states its rule deliberately:
Reading the declaring line rather than describing it is deliberate. A summary would be a second thing to keep true; the source cannot go stale.
A /** … */ comment does not break that rule — it is in the source, beside the declaration, and moves with it. It is the one kind of description that cannot drift from the thing it describes. The rendered hover should show both: the comment, then the declaring line it belongs to.
Note on convention
No .htm in the repo uses /** … */ yet; // comments are the established form inside an attribute list (see kits/bootstrap-kit/parts/navbar.htm, which uses them for // parameters / // private section markers and for prose). So this establishes the doc-comment convention rather than surfacing an existing one — /** … */ for "this is documentation for the next parameter", // staying an ordinary aside. Worth landing a couple of real ones in bootstrap-kit alongside the feature, so it has something to show.
A
<:define>can already carry a JSDoc-style comment beside a parameter, and nothing surfaces it:This compiles today. The comment parses, is stripped, and does not reach the output — so this is entirely an extension-side feature, with no compiler change needed.
What it should do
Hovering
::widthat a usage site, and completing it, should show "How wide the box is. Any CSS length."Where it lands
src/hovers.ts—findHover()resolves a declaration and renders the declaring line.src/completions.ts— parameter items already carry adetailtaken from the declaration's source location.Both already find the declaration; neither looks at what sits above it.
The design point worth keeping
hovers.tsstates its rule deliberately:A
/** … */comment does not break that rule — it is in the source, beside the declaration, and moves with it. It is the one kind of description that cannot drift from the thing it describes. The rendered hover should show both: the comment, then the declaring line it belongs to.Note on convention
No
.htmin the repo uses/** … */yet;//comments are the established form inside an attribute list (seekits/bootstrap-kit/parts/navbar.htm, which uses them for// parameters/// privatesection markers and for prose). So this establishes the doc-comment convention rather than surfacing an existing one —/** … */for "this is documentation for the next parameter",//staying an ordinary aside. Worth landing a couple of real ones inbootstrap-kitalongside the feature, so it has something to show.