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. 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` 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. Declaration- and statement-level only — in a `@module` comment it has no effect and warns
`@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). A bare key matches the parameter name; a dotted key (obj.prop) documents a property of a named object parameter.

Dotted keys whose root segment is a real parameter (obj in obj.prop) land in ParameterJson's propertyDescriptions record, keyed by the sub-path (obj.prop → prop, obj.a.b → a.b). The property segment is not validated against the parameter's type. Matching is by parameter name, so destructured parameters (fn({a, b}: T), which TypeScript names __0) are not covered.

A key matching no parameter — or a dotted key whose root segment matches none — drops its description and fires an unknown_param diagnostic with the orphaned key, usually a typo or stale doc after a rename. 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, or @nodocs in a @module comment (no module-level meaning — use exclude patterns to omit a module)
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.