tags #

svelte-docinfo extracts TSDoc/JSDoc tags from source comments and surfaces them as structured fields on the output. This page lists every tag that is parsed, where its value lands, and the rules that decide which symbol receives it.

Supported tags
#

Tag	Where it lands
`@param`	ParameterJson.`description` on the matching parameter. Unmatched keys emit `unknown_param`
`@returns`	`returnDescription` on functions, function members, and per-overload OverloadJson. `@return` is not accepted
`@throws`	`throws` array on the parent declaration. `{Type}` hints are extracted as the leading error type
`@example`	`examples` array on the parent declaration
`@deprecated`	`deprecatedMessage` on the parent declaration. Empty body still marks the symbol deprecated
`@see`	`seeAlso` array. Plain URLs, `{@link}` syntax, and module names all preserved in their source form
`@since`	`since` string on the parent declaration
`@default`	`defaultValue` on variable declarations and variable members; falls back for ComponentPropJson.`defaultValue` when no destructuring default is present
`@mutates`	`mutates` record. Non-standard; same format as `@param`: `@mutates key - description`
`@nodocs`	Excludes the declaration from output entirely; also excludes it from flat-namespace duplicate checking
`@module`	Promotes the comment to ModuleJson.`moduleComment` instead of attaching to a declaration

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, @since, @see, @throws, @mutates, @default, @nodocs. These describe the symbol as a whole and live on the parent declaration only.

Placing a symbol-scope tag on a non-primary overload emits misplaced_tag and the tag is dropped, with no synthetic content and no silent loss. Move it to the primary signature (typically the first overload, or the implementation signature's JSDoc which feeds the symbol-level extraction). See diagnostics for the diagnostic details.

/**
 * @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 actual parameter names. The leading - separator is stripped (TypeScript's parser keeps it as syntax, not content). Destructured parameters match the outer binding name, not inner properties.

When a key doesn't match any parameter (a typo, a stale doc after a rename, or a description of a destructured property), the description is dropped and an unknown_param diagnostic fires with the orphaned key. Fix the JSDoc rather than relying on the silent fallback.

@mutates
#

Non-standard tag for documenting mutations to parameters or external state. Same key - description format as @param, but keys are not validated against the parameter list. Anything goes:

a parameter name: @mutates options - sets defaults in place
a compound path: @mutates this.cache - inserts the result
an external state reference: @mutates global_registry - registers the handler

The output is a Record<string, string> mapping each key to its description. Consumers decide how to render or group by key shape.

@nodocs
#

@nodocs on a declaration removes it from the analysis output entirely. Two follow-on effects:

Flat-namespace duplicate checking skips it: a hidden helper named parse can coexist with a public parse in another module without triggering duplicate_declaration.
Re-export synthesis is suppressed: @nodocs on a re-export statement drops both the alsoExportedFrom link and any synthesized alias declaration. The canonical entry stays untouched.

@module
#

A comment tagged @module attaches to the file rather than to the next declaration. The text lands on ModuleJson.moduleComment and is suppressed from any declaration docComment that might otherwise capture it.

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

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

Svelte files have a second module-comment source: an HTML comment directly above <script>. When both an HTML and a JSDoc @module comment supply a value for the same target, duplicate_comment fires with commentType: "module_comment". The same diagnostic covers declaration-level collisions (commentType: "doc_comment").

Re-exports inherit comments selectively
#

A re-export that carries its own JSDoc synthesizes an alias in the re-exporting module so the local content has somewhere to live, even when the name is unchanged. See Re-exports for the full encoding rules and merge order.

Tag-related diagnostics
#

Three diagnostic kinds surface tag-handling problems:

misplaced_tag: symbol-scope tag on a non-primary overload signature
unknown_param: @param key with no matching parameter
duplicate_comment: two sources supplied a comment for the same target (HTML + JSDoc @module, or any other collision)

All three are warnings; analysis still completes and the declaration is included. See tsdoc.ts for the parser internals and diagnostics for the full diagnostic schema.