or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

ast-nodes.md configuration.md emitters.md index.md parser.md standard-tags.md transforms.md

tile.json

tessl/npm-microsoft--tsdoc

A parser for the TypeScript doc comment syntax

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/@microsoft/tsdoc@0.15.x

To install, run

npx @tessl/cli install tessl/npm-microsoft--tsdoc@0.15.0

@microsoft/tsdoc

@microsoft/tsdoc is a reference implementation parser for the TSDoc syntax, which is a proposal to standardize documentation comments used in TypeScript source files. The library enables different tools to extract content from TypeScript documentation comments without conflicts, supporting a standardized syntax similar to JSDoc but specifically designed for TypeScript.

Package Information

Package Name: @microsoft/tsdoc
Package Type: npm
Language: TypeScript
Installation: npm install @microsoft/tsdoc

Core Imports

import { TSDocParser, TSDocConfiguration } from "@microsoft/tsdoc";

For CommonJS:

const { TSDocParser, TSDocConfiguration } = require("@microsoft/tsdoc");

Basic Usage

import { TSDocParser, TSDocConfiguration } from "@microsoft/tsdoc";

// Create configuration and parser
const configuration = new TSDocConfiguration();
const tsdocParser = new TSDocParser(configuration);

// Parse a TSDoc comment
const parserContext = tsdocParser.parseString(`
  /**
   * Calculates the area of a rectangle.
   * @param width - The width of the rectangle
   * @param height - The height of the rectangle  
   * @returns The area as a number
   */
`);

// Access the parsed AST
const docComment = parserContext.docComment;
console.log(docComment.summarySection); // Access summary content
console.log(parserContext.log.messages); // Check for parsing errors

Architecture

@microsoft/tsdoc is built around several key components:

Configuration System: TSDoc configurations, tag definitions, and validation rules that define parsing behavior
Parser Engine: Core parser that converts TSDoc comment text into structured AST nodes
AST Nodes: 45+ DocNode classes representing all parts of TSDoc comments (text, tags, code blocks, links, etc.)
Standard Tags: Comprehensive registry of 75+ standard TSDoc tag definitions organized by standardization level
Emitters: Utilities for rendering AST back to TSDoc markup or extracting plain text
Transforms: AST manipulation utilities for cleaning and modifying parsed comment trees

Capabilities

Configuration Management

Configuration system for defining TSDoc parsing behavior, tag definitions, validation rules, and custom DocNode types.

class TSDocConfiguration {
  constructor();
  addTagDefinition(tagDefinition: TSDocTagDefinition): void;
  tryGetTagDefinition(tagName: string): TSDocTagDefinition | undefined;
  isTagSupported(tagDefinition: TSDocTagDefinition): boolean;
  setSupportForTag(tagDefinition: TSDocTagDefinition, supported: boolean): void;
}

class TSDocTagDefinition {
  constructor(parameters: ITSDocTagDefinitionParameters);
  readonly tagName: string;
  readonly syntaxKind: TSDocTagSyntaxKind;
  readonly allowMultiple: boolean;
}

enum TSDocTagSyntaxKind {
  InlineTag = "InlineTag",
  BlockTag = "BlockTag", 
  ModifierTag = "ModifierTag"
}

Configuration

TSDoc Parser

Core parser engine that converts TSDoc comment text into structured AST nodes with comprehensive error reporting.

class TSDocParser {
  constructor(configuration?: TSDocConfiguration);
  parseString(text: string): ParserContext;
  parseRange(textRange: TextRange): ParserContext;
}

class ParserContext {
  readonly configuration: TSDocConfiguration;
  readonly commentRange: TextRange;
  readonly sourceRange: TextRange;
  readonly docComment: DocComment;
  readonly log: ParserMessageLog;
}

Parser

AST Node Types

Comprehensive set of 45+ DocNode classes representing all parts of TSDoc comments including text, tags, code blocks, links, and HTML elements.

abstract class DocNode {
  readonly kind: string;
  readonly parent: DocNode | undefined;
  getChildNodes(): ReadonlyArray<DocNode | undefined>;
}

class DocComment extends DocNode {
  readonly summarySection: DocSection;
  readonly remarksBlock: DocBlock | undefined;
  readonly parameterBlocks: ReadonlyArray<DocParamBlock>;
  readonly returnsBlock: DocBlock | undefined;
  readonly modifierTagSet: StandardModifierTagSet;
}

AST Nodes

Standard Tags Registry

Comprehensive collection of 75+ predefined TSDoc tag definitions organized by standardization level (Core, Extended, Discretionary).

class StandardTags {
  static readonly allDefinitions: ReadonlyArray<TSDocTagDefinition>;
  static readonly param: TSDocTagDefinition;
  static readonly returns: TSDocTagDefinition;
  static readonly remarks: TSDocTagDefinition;
  static readonly example: TSDocTagDefinition;
  static readonly public: TSDocTagDefinition;
  static readonly beta: TSDocTagDefinition;
  static readonly alpha: TSDocTagDefinition;
}

enum Standardization {
  None = "None",
  Core = "Core",
  Extended = "Extended", 
  Discretionary = "Discretionary"
}

Standard Tags

Content Emitters

Utilities for rendering DocNode trees back to TSDoc markup or extracting plain text content from parsed comments.

class TSDocEmitter {
  constructor();
  renderDocNode(docNode: DocNode): string;
  renderDocComment(docComment: DocComment): string;
}

class PlainTextEmitter {
  constructor();
  renderDocNode(docNode: DocNode): string;
  renderDocComment(docComment: DocComment): string;
}

Emitters

AST Node Transforms

Helper utilities for transforming and manipulating DocNode trees after parsing, commonly used for cleaning up comments for rendering.

class DocNodeTransforms {
  static trimSpacesInParagraphNodes(docParagraph: DocParagraph): ReadonlyArray<DocNode>;
}

Transforms

Common Types

interface ITSDocTagDefinitionParameters {
  tagName: string;
  syntaxKind: TSDocTagSyntaxKind;
  allowMultiple?: boolean;
}

interface IParserMessageParameters {
  messageId: TSDocMessageId;
  messageText: string;
  textRange: TextRange;
  tokenSequence?: TokenSequence;
}

interface ITextLocation {
  line: number;
  column: number;
}

interface IStringBuilder {
  append(text: string): void;
  toString(): string;
}

interface IDocNodeDefinition {
  docNodeKind: string;
  constructor: DocNodeConstructor;
}

interface ITokenSequenceParameters {
  parserContext: ParserContext;
  tokens: ReadonlyArray<Token>;
  startIndex: number;
  endIndex: number;
}

type DocNodeConstructor = new (...args: any[]) => DocNode;

enum TSDocMessageId {
  None = "None",
  ReferenceMissingMemberName = "ReferenceMissingMemberName",
  AtSignWithoutTag = "AtSignWithoutTag",
  UnsupportedTag = "UnsupportedTag",
  InlineTagMissingBraces = "InlineTagMissingBraces",
  TagShouldNotHaveNonePart = "TagShouldNotHaveNonePart",
  InheritDocTagShouldNotHaveOtherContent = "InheritDocTagShouldNotHaveOtherContent",
  UnexpectedEndOfInput = "UnexpectedEndOfInput",
  MissingTag = "MissingTag",
  // ... 50+ more message IDs for comprehensive error reporting
}

enum TokenKind {
  AsciiWord = "AsciiWord",
  Other = "Other",
  Newline = "Newline",
  EndOfInput = "EndOfInput",
  Spacing = "Spacing",
  LeftCurlyBracket = "LeftCurlyBracket",
  RightCurlyBracket = "RightCurlyBracket",
  AtSign = "AtSign",
  Backslash = "Backslash",
  // ... additional token types for lexical analysis
}

enum ExcerptKind {
  Content = "Content",
  Spacing = "Spacing",
  BlockTag = "BlockTag",
  InlineTag = "InlineTag"
}