tsdoc.ts

TSDoc/JSDoc parsing helpers using the TypeScript compiler API.

Provides parseComment for extracting JSDoc/TSDoc from TypeScript nodes. Primarily designed for build-time code generation but can be used at runtime.

Design

Pure extraction approach: extracts documentation as-is with minimal transformation, preserving source intent. Works around TypeScript compiler API quirks where needed.

Supports both regular TypeScript and Svelte components (via svelte2tsx output).

Tag support

Supports the common JSDoc/TSDoc doc tags as used across the TypeScript ecosystem: @param, @returns, @throws, @example, @deprecated, @internal, @see, @since, @default, @nodocs. Where the two standards spell a tag differently, both spellings are accepted: @return (JSDoc synonym) parses like @returns, and @defaultValue (the TSDoc spelling, plus JSDoc's lowercase @defaultvalue synonym) parses like @default.

@internal is a marker, not an exclusion: it means "not stable public API" and lands as internalMessage (with any trailing prose; empty string for a bare tag) while the declaration stays documented. Use @nodocs to exclude a declaration from output entirely.

The @nodocs tag excludes exports from documentation and flat namespace validation. The declaration is still exported and usable, just not documented.

Also supports @mutates (non-standard) for documenting mutations to parameters or external state. Uses same format as @param: @mutates key - description of mutation. The key is unvalidated — typically a parameter name, but compound paths (this.foo, obj.field) and external state references are accepted as-is.

The @see tag supports multiple formats: plain URLs (https://...), {@link} syntax, and module names. Relative/absolute path support in @see is TBD.

Behavioral notes

JSDoc blocks tagged @module are excluded from parseComment entirely (text and tags) — module comments attach to the file's first statement in the AST and are owned by extractModuleComment instead.

JSDocPropertyLikeTag nodes (@property/@param declaring a symbol in a typedef or callback) parse to their own tag description — the only doc such a declaration can carry.

Due to TS Compiler API limitations:

TS API includes dash separator in @param tag text; we strip the leading - as it's syntax, not content
@throws tags have {Type} stripped by TS API; fallback regex extracts first word as error type
TS API strips URL protocols from @see tag text; we use getText() to preserve original format including {@link} syntax

@see declaration-build.ts for DeclarationJsonBuild @see typescript-exports.ts and svelte.ts as primary consumers

view source

Declarations
#

5 declarations

applyToDeclaration
#

tsdoc.ts view source

(declaration: MemberJsonBuild | DeclarationJsonBuild, tsdoc: TsdocParsedComment | undefined, isMember?: boolean): void import {applyToDeclaration} from 'svelte-docinfo/tsdoc.js';

Apply parsed TSDoc metadata to a declaration.

Consolidates the common pattern of assigning TSDoc fields to declarations, with conditional assignment for array fields (only if non-empty).

`declaration`

declaration object to update

type MemberJsonBuild | DeclarationJsonBuild

`tsdoc`

parsed TSDoc comment (if available)

type TsdocParsedComment | undefined

`isMember`

whether declaration is a member of a container; function *members* carry defaultValue (the documented behavior when a callback is omitted) while top-level function declarations never do

type boolean

default false

returns

void

mutates

declaration — adds docComment, deprecatedMessage, internalMessage, examples, seeAlso, throws, since, mutates, defaultValue fields

cleanComment
#

tsdoc.ts view source

(commentText: string): string | undefined import {cleanComment} from 'svelte-docinfo/tsdoc.js';

Clean raw JSDoc comment text by removing comment markers and leading asterisks.

Transforms /** ... *\/ style comments into clean text.

`commentText`

the raw comment text including /** and *\/ markers

type string

returns

string | undefined

cleaned comment text, or undefined if empty after cleaning

examples

cleanComment('/** Hello world *\/') // => 'Hello world'
cleanComment('/**\n * Line 1\n * Line 2\n *\/') // => 'Line 1\nLine 2'

hasDocContent
#

tsdoc.ts view source

({ text, params, ...tags }: TsdocParsedComment): boolean import {hasDocContent} from 'svelte-docinfo/tsdoc.js';

Whether a parsed comment carries any documentation — description text or an extracted tag.

Type machinery parses to an empty result (@type/@typedef/@template tags populate no fields), so doc-hunting walks (component docComment) use this to keep lower-precedence sources like the HTML @component comment reachable instead of letting an annotation claim the doc slot with empty text. Structural over the parsed result — any field beyond text/params counts when present — so it can't drift from parseComment's extraction or from TsdocParsedComment gaining fields.

`__0`

type TsdocParsedComment

returns

boolean

parseComment
#

tsdoc.ts view source

(node: Node, sourceFile?: SourceFile): TsdocParsedComment | undefined import {parseComment} from 'svelte-docinfo/tsdoc.js';

Parse JSDoc comment from a TypeScript node.

Extracts and parses all JSDoc tags including:

@param - parameter descriptions
@returns - return value description (@return accepted as a synonym)
@throws - error documentation
@example - code examples
@deprecated - deprecation warnings
@internal - internal-API marker (trailing prose kept)
@see - related references
@since - version information
@default - default value (@defaultValue/@defaultvalue accepted as synonyms)
@mutates - mutation documentation (non-standard)
@nodocs - exclusion flag (non-standard)

JSDoc blocks tagged @module are excluded entirely (text and tags): a module comment attaches to the file's first statement in the AST, and without the filter it would read as that statement's own docs. extractModuleComment (typescript-exports.ts) owns module comments.

`node`

the TypeScript node to extract JSDoc from

type Node

`sourceFile`

source file for full-text tag reads (@see); defaults to the node's own

type SourceFile

default node.getSourceFile()

returns

TsdocParsedComment | undefined

parsed comment with structured metadata, or undefined if no JSDoc found (or only @module blocks)

examples

const tsdoc = parseComment(declarationNode, sourceFile);
if (tsdoc) {
  console.log(tsdoc.text); // main comment text
  console.log(tsdoc.params); // {paramName: 'description'}
}

TsdocParsedComment
#

tsdoc.ts view source

TsdocParsedComment import type {TsdocParsedComment} from 'svelte-docinfo/tsdoc.js';

Parsed JSDoc/TSDoc comment with structured metadata.

Returned by parseComment — consumers typically pass this to applyToDeclaration to populate DeclarationJsonBuild fields.

`text`

Comment text (excluding comment markers).

type string

`params`

Parameter descriptions mapped by parameter name.

type Record<string, string>

`returns?`

Return value description from @returns (or its JSDoc @return synonym).

type string

`throws?`

Thrown errors from @throws.

type { type?: string | undefined; description: string; }[]

`examples?`

Code examples from @example.

type string[]

`deprecatedMessage?`

Deprecation message from @deprecated.

type string

`internalMessage?`

Internal-API marker from @internal. Presence means the tag was written; an empty string is a bare tag with no trailing prose. Means "not stable public API" — the declaration is still documented (use @nodocs to exclude from output).

type string

`seeAlso?`

Related references from @see.

type string[]

`since?`

Version information from @since.

type string

`defaultValue?`

Default value from @default (or its @defaultValue/@defaultvalue spellings).

type string

`mutates?`

Mutation documentation from @mutates (non-standard), mapped by parameter name.

type Record<string, string>

`nodocs?`

Whether to exclude from documentation. From @nodocs tag.

type boolean

Depends on
#

declaration-build.ts