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
#

TagWhere it lands
@paramParameterJson.description on the matching parameter. Dotted keys (obj.prop) land in propertyDescriptions. Keys matching no parameter emit unknown_param
@returnsreturnDescription on functions, function members, and per-overload OverloadJson. @return (JSDoc synonym) parses identically
@throwsthrows 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
@exampleexamples array on the parent declaration
@deprecateddeprecatedMessage on the parent declaration. An empty body still marks the symbol deprecated
@internalinternalMessage on the parent declaration, member, or component prop. A marker, not an exclusion (see @internal)
@seeseeAlso array, each entry in its source form (URLs, {@link}, module names)
@sincesince string on the parent declaration
@defaultdefaultValue 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
@mutatesmutates record of target to description (see @mutates)
@nodocsExcludes 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
@csspropA 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
@moduleMakes 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: @param and @returns. These flow to the matching overload's parameters[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 named parse can coexist with a public parse in another module without duplicate_declaration.
  • Re-exports: on a re-export statement, it drops the alsoExportedFrom link, any synthesized alias, and the module's reExports, starExports, or externalReExports / externalStarExports entry. The canonical declaration is unaffected. In JS, a @nodocs in a @typedef block above the statement hides the typedef instead, and the re-export stays.
  • Merged value+type pairs: a const Foo + type Foo pair 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.