The doc comments were mostly TSDoc already: no {type} annotations, {@link} for references, @param, @returns, @throws and @example as the only standard tags. Nothing said which dialect they were in, and nothing checked. Run through @microsoft/tsdoc, the reference parser, the 1,909 doc comments across src/, scripts/, test/, tools/ and www/ produced 324 findings, all JSDoc habits:
@throws {RangeError} …, 135 of them. To TSDoc the braces open a malformed inline tag.
@param name description with no hyphen, 19 of them.
@param options.key for one field of an options object, 6 of them. TSDoc has no form for this.
A code span wrapped across a line break, which TSDoc does not allow, and a bare <, >, { or } in prose that TSDoc takes for markup. About 20 in all.
Doc comments are TSDoc. scripts/check-tsdoc.ts (pnpm run tsdoc:check, in the invariants gate) parses every comment TypeScript attaches to a declaration in any of the three typechecked projects and fails on every TSDoc diagnostic, including an undefined tag. It reads the comments from the compiler's AST, so a /** inside a string is not mistaken for one.
@microsoft/tsdoc is a devDependency. It has no dependencies of its own. @microsoft/tsdoc-config was not taken, because it pulls in a JSON schema validator to read a file whose only content here is one tag definition.
Tags beyond the standard set are declared in tsdoc.json, the file editor plugins and API Extractor read. Today that is @unpublished, the block tag check-public-types.ts honours.
Two conventions follow from the parsers, not from taste:
@throws opens with the error type as a plain word:@throws RangeError if …. TSDoc suggests @throws {@link RangeError}, but TypeScript still reads braces after @throws as a JSDoc type expression. {@link …} is not one, so the parse eats the rest of the comment and editor hovers show a lone {. A plain first word survives both parsers. gen-docs.ts treats it as the subject, links it when it can, and fails on a @throws that does not open with one.
An options object documents its fields on the type, as property doc comments, in place of @param options.key. Hovers show these on the property, which is where a caller is looking.
A JSDoc-ism fails verify --full and CI with a file and line, not a review comment.
The generated reference renders @param name - description without the hyphen, and a @throws followed by a comma no longer gets a stray space before it.
The check takes about 0.8 s. It opens the same three projects as typecheck.
ADR 0006 still calls the comments "JSDoc" where it names TypeScript's API, which keeps that name. The prose convention is this ADR.
ADR 0044: Doc comments are TSDoc
Status: Accepted (2026-10-14)
Context
The doc comments were mostly TSDoc already: no
{type}annotations,{@link}for references,@param,@returns,@throwsand@exampleas the only standard tags. Nothing said which dialect they were in, and nothing checked. Run through@microsoft/tsdoc, the reference parser, the 1,909 doc comments acrosssrc/,scripts/,test/,tools/andwww/produced 324 findings, all JSDoc habits:@throws {RangeError} …, 135 of them. To TSDoc the braces open a malformed inline tag.@param name descriptionwith no hyphen, 19 of them.@param options.keyfor one field of an options object, 6 of them. TSDoc has no form for this.<,>,{or}in prose that TSDoc takes for markup. About 20 in all.Decision
Doc comments are TSDoc.
scripts/check-tsdoc.ts(pnpm run tsdoc:check, in theinvariantsgate) parses every comment TypeScript attaches to a declaration in any of the three typechecked projects and fails on every TSDoc diagnostic, including an undefined tag. It reads the comments from the compiler's AST, so a/**inside a string is not mistaken for one.@microsoft/tsdocis a devDependency. It has no dependencies of its own.@microsoft/tsdoc-configwas not taken, because it pulls in a JSON schema validator to read a file whose only content here is one tag definition.Tags beyond the standard set are declared in
tsdoc.json, the file editor plugins and API Extractor read. Today that is@unpublished, the block tagcheck-public-types.tshonours.Two conventions follow from the parsers, not from taste:
@throwsopens with the error type as a plain word:@throws RangeError if …. TSDoc suggests@throws {@link RangeError}, but TypeScript still reads braces after@throwsas a JSDoc type expression.{@link …}is not one, so the parse eats the rest of the comment and editor hovers show a lone{. A plain first word survives both parsers.gen-docs.tstreats it as the subject, links it when it can, and fails on a@throwsthat does not open with one.@param options.key. Hovers show these on the property, which is where a caller is looking.Consequences
verify --fulland CI with a file and line, not a review comment.@param name - descriptionwithout the hyphen, and a@throwsfollowed by a comma no longer gets a stray space before it.typecheck.