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.

The set is the common tags of JSDoc and the TSDoc spec, plus the custom @nodocs and @mutates. Where the standards spell a tag differently, both spellings work (@default / @defaultValue, @return / @returns).

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
`@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 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 or overloads. `@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 and does nothing, and on a member or component prop it silently does nothing
`@module`	Makes the comment ModuleJson.`moduleComment` instead of a declaration's doc

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.

A symbol-scope tag on a non-primary overload emits misplaced_tag and is dropped. Put these tags on the first overload signature: its JSDoc documents the symbol, while JSDoc on a later overload documents only that overload.

/**
 * @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.
Merged value+type pairs: a const Foo + type Foo pair is one symbol, so the tag on either excludes it.

@module
#

A comment tagged @module documents the file, not the next declaration. The text lands on ModuleJson.moduleComment and never in a declaration's docComment.

/**
 * Date math utilities.
 *
 * @module
 */

export function add_days(d: Date, n: number): Date { /* ... */ }

Svelte files have three module-comment sources, in priority order: a JSDoc @module in the instance <script>, one in <script module>, and the first HTML  comment with @module at a line start. The highest-priority source wins, and more than one emits duplicate_comment (commentType: "module_comment"). Likewise, an HTML @component comment plus in-script component JSDoc emits it with commentType: "doc_comment", and the JSDoc wins.

Re-exports inherit comments selectively
#

A re-export with its own JSDoc synthesizes an alias in the re-exporting module, even when the name is unchanged. Its local doc fields win and the canonical's fill gaps. See Re-exports.

Tag-related diagnostics
#

Three diagnostic kinds report tag problems, all warnings:

misplaced_tag: a symbol-scope tag on a non-primary overload, or @nodocs in a @module comment
unknown_param: @param key with no matching parameter
duplicate_comment: more than one @module source in a Svelte file, or an HTML @component comment plus in-script component JSDoc

See diagnostics for details and tsdoc.ts for the parser.