tags #
svelte-docinfo extracts TSDoc/JSDoc tags from source comments into structured fields on the output. This page lists every parsed tag, where its
value lands, and which symbol receives it. JSDoc's type tags (@type, @typedef, @template, @overload) are covered in JS and JSDoc.
The set is the common tags of JSDoc and the TSDoc spec, plus the custom @nodocs and @mutates, and the Custom Elements Manifest's @cssprop for a
component's CSS custom properties. Where the standards spell a tag differently, both spellings
work (@default / @defaultValue, @return / @returns, @cssprop / @cssproperty).
Inline tags like {@link} are kept in the extracted text for the consumer to
render. TypeScript reprints {@link A|b} as {@link A |b}; @see keeps its source text exactly. Please open an issue if a tag you need is
missing or off-spec.
Supported tags #
| Tag | Where it lands |
|---|---|
@param | ParameterJson.description on the matching
parameter. Dotted keys (obj.prop) land in propertyDescriptions. Keys matching no parameter emit unknown_param |
@returns | returnDescription on functions, function members, and per-overload OverloadJson. @return (JSDoc synonym) parses
identically |
@throws | throws array on the parent declaration. A braced type
(@throws {TypeError} - description, unions included) lands in type; the description may be empty or multiline. Without braces the first
word is the type (@throws TypeError if …), so @throws if … records if as the type. A lone unbraced word is the description |
@example | examples array on the parent declaration |
@deprecated | deprecatedMessage on the parent declaration. An empty body still marks
the symbol deprecated |
@internal | internalMessage on the parent declaration, member, or component prop. A
marker, not an exclusion (see @internal) |
@see | seeAlso array, each entry in its source form (URLs, {@link}, module names) |
@since | since string on the parent declaration |
@default | defaultValue on variable declarations and on variable and function
members (for a function member, the behavior when the callback is omitted). Also fills ComponentPropJson.defaultValue when the prop
has no destructuring default. Never on top-level functions, overloads, or
constructors. @defaultValue and @defaultvalue parse
identically |
@mutates | mutates record of target to description (see @mutates) |
@nodocs | Excludes the declaration from output and from the opt-in duplicate-name check (see @nodocs). Applies to declarations and export statements only: in
a @module comment it warns misplaced_tag and is dropped, and
on a member or component prop it silently does nothing |
@cssprop | A Svelte component's CSS custom property, in ComponentDeclarationJson.cssCustomProperties (see component styling). Read from the component's doc comment
only; on any other declaration or in a @module comment it warns misplaced_tag and is dropped. @cssproperty parses
identically |
@module | Makes the comment document the file: its prose becomes ModuleJson.moduleComment and its tags the
module's own fields, instead of a declaration's doc (see @module) |
Symbol-scope vs signature-scope #
Two tags vary per overload signature; the rest describe the symbol as a whole.
- Signature-scope:
@paramand@returns. These flow to the matching overload'sparameters[i].description/returnDescription. Each overload can carry its own. - Symbol-scope:
@example,@deprecated,@internal,@since,@see,@throws,@mutates,@default,@nodocs. These describe the symbol as a whole and live on the parent declaration only.
Put symbol-scope tags on the first overload: its JSDoc documents the symbol, while JSDoc on
a later overload documents only that overload, and a symbol-scope tag there warns misplaced_tag. JSDoc on the implementation is hidden and warns implementation_doc_hidden. For JS @overload tags, see JS and JSDoc.
/**
* @example double(2) // 4
* @deprecated use `scale` instead
*/
export function double(n: number): number;
export function double(n: bigint): bigint;
export function double(n: number | bigint): number | bigint {
return (n as any) * 2;
}@param matching and unknown_param #
@param keys are matched against parameter names, and the leading - separator is stripped from the description. A dotted key (obj.prop) documents a
property of a named object parameter.
Dotted keys land in ParameterJson's propertyDescriptions, keyed by sub-path (obj.prop → prop, obj.a.b → a.b). The property path isn't checked
against the parameter's type. Destructured parameters
(fn({a, b}: T), which TypeScript names __0) can't be matched by name, so they aren't covered.
A key whose name (or dotted root) matches no parameter drops its description and emits unknown_param with the key, usually a typo or a stale doc after a rename.
@mutates #
A non-standard tag for documenting mutations to parameters or external state: @mutates target - description. The target is everything before the first - (space-hyphen-space), so unlike @param it can be a
hyphenated name or a phrase. Targets are not validated against the
parameters, and backticks are stripped, so `options` and options are the same key:
- a parameter name:
@mutates options - sets defaults in place - a compound path:
@mutates this.cache - inserts the result - a multi-word external reference:
@mutates `app_settings` row - bumps the revision - a bare target with no description:
@mutates `this`
The output is a Record<string, string> of target to
description, empty for the bare form. Without a separator, the first line is the target and
any following lines are the description.
On a component prop, @mutates declares that the component writes into the
object or array it's handed, the same contract a function declares for a parameter: @mutates items - appends the selected entry. Reassigning a prop isn't a
mutation in this sense; bindable covers that. The two combine: Svelte warns
when a component mutates state the parent didn't bind, so an in-place write into a parent's $state usually sits on a $bindable prop.
@internal #
@internal marks a symbol as not stable public API, per TSDoc. It lands as internalMessage on declarations and members of every kind, and on component
props: an empty string for a bare tag, or the trailing prose
(@internal used during development), kept separate from docComment.
It's a marker, not an exclusion: the declaration stays fully documented, so
consumers can badge or filter it. To remove a declaration from output, use @nodocs; to omit whole modules, use exclude patterns.
@nodocs #
@nodocs on a declaration removes it from the output entirely. It doesn't apply
to members or component props, which stay in the output with no warning. It also affects:
- Duplicate checking (opt-in, via
onDuplicates): a hidden helper namedparsecan coexist with a publicparsein another module withoutduplicate_declaration. - Re-exports: on a re-export statement, it drops the
alsoExportedFromlink, any synthesized alias, and the module'sreExports,starExports, orexternalReExports/externalStarExportsentry. The canonical declaration is unaffected. In JS, a@nodocsin a@typedefblock above the statement hides the typedef instead, and the re-export stays. - Merged value+type pairs: a
const Foo+type Foopair is one symbol, so the tag on either excludes it.
@cssprop #
@cssprop {<syntax>} [--name=default] - description documents a CSS custom
property in a Svelte component's doc comment, in the Custom Elements Manifest form; the
syntax and brackets are optional. A tag naming no -- property warns malformed_tag and is dropped; a second tag for the same name warns duplicate_tag and the first wins. The bracketed default lands in default, beside the fallback the style gives; when the two
disagree, cssprop_default_mismatch warns. See component styling.
@module #
A comment tagged @module documents the file, not the next declaration. Its
prose lands on ModuleJson.moduleComment and never in a declaration's docComment. Its tags parse as a declaration's do, into the module's fields of
the same names: examples, deprecatedMessage, seeAlso, since, and internalMessage. Tags that only describe a declaration
(@param, @returns, @mutates, @throws, @default, @nodocs, @cssprop) warn misplaced_tag and are dropped, and unknown tags drop silently. A comment of
tags alone has no moduleComment. In a module comment only an @ that starts a line starts a tag, so a mid-line @ stays in the text. The comment
counts as a module comment only when a line starts with @module (a one-line /** @module */ counts); in /** Text @module */ the text documents the next
declaration instead.
/**
* Date math utilities.
*
* @see https://tc39.es/proposal-temporal/
* @since 0.2.0
* @module
*/
export function add_days(d: Date, n: number): Date { /* ... */ } A Svelte file's module comment comes from the first of: a JSDoc @module in the
instance <script>, one in <script module>, and an HTML comment with @module at a line start. More than one warns duplicate_comment.
A component's doc comment is its JSDoc above $props(), else its HTML @component comment, the first with @component at a line start. A
JSDoc with prose beside an HTML comment warns duplicate_comment. Editor hover
takes the last comment containing @component anywhere, so component_comment_mismatch warns when the two picks differ.
Tag-related diagnostics #
Tag problems surface as warnings: misplaced_tag, implementation_doc_hidden, unknown_param, unknown_cssprop, and duplicate_comment, described in the sections
above and in diagnostics. The parser is tsdoc.ts.