TSDoc Documentation

TSDoc is a documentation standard for TypeScript. It provides a structured way to write comments that can be parsed by tools to generate documentation or perform static analysis.

Key resources for users:

• Project Overview & Roadmap: https://tsdoc.org/
• Tag Reference: Learn about syntax elements like @param, @remarks, etc. at https://tsdoc.org/pages/tags/alpha/
• Interactive Playground: Test the parser engine at https://tsdoc.org/play
• Community Support: Join the Zulip chat room for live help.

The tsdoc-build-rig package is a specialized build rig designed for projects within the TSDoc repository that utilize Heft for building. It extends @rushstack/heft-node-rig and @rushstack/heft-web-rig by adding configuration options specific to the TSDoc repository environment.

Note: This package is not published to the NPM registry and is intended for internal use within the TSDoc repository.

This monorepo contains several packages for working with TSDoc:

• @microsoft/tsdoc: The core parser library.
• @microsoft/tsdoc-config: A loader for tsdoc.json configuration files.
• eslint-plugin-tsdoc: An ESLint plugin to enforce TSDoc standards.
• api-demo: Code samples demonstrating how to use the @microsoft/tsdoc parser.

TSDoc is a standardized proposal for doc comments in TypeScript source files. It enables different tools to reliably extract documentation content from comments using a consistent syntax. A typical TSDoc comment uses tags like @remarks, @param, @returns, and @beta within a standard JSDoc-style block.

export class Statistics {
  /**
   * Returns the average of two numbers.
   *
   * @remarks
   * This method is part of the {@link core-library#Statistics | Statistics subsystem}.
   *
   * @param x - The first input number
   * @param y - The second input number
   * @returns The arithmetic mean of `x` and `y`
   *
   * @beta
   */
  public static getAverage(x: number, y: number): number {
    return (x + y) / 2.0;
  }
}

Use this option to quickly try out the @microsoft/tsdoc API using the latest official release. This method does not symlink to local builds of the library.

Note: If you are contributing a fix to the TSDoc repository, use the Rush method instead.

$ cd ./api-demo
# Use --no-package-lock to avoid conflicts with Rush
$ npm install --no-package-lock
$ npm run build

# To run the simple demo (direct source parsing):
$ npm run simple

# To run the advanced demo (TypeScript AST extraction):
$ npm run advanced

Use this option if you are a contributor submitting a pull request. This method links api-demo to your local build of the @microsoft/tsdoc library for testing and validation. This requires the Rush monorepo manager.

Warning: After running rush install, the repository is in a "Rush-linked" state. Do not run npm install in this state. To return to standalone mode, run rush unlink && rush purge.

# 1. Install Rush globally
$ npm install -g @microsoft/rush

# 2. Install dependencies for the entire monorepo (run from the repo root)
$ rush install

# 3. Build all projects
$ rush build

# 4. Build and run the demo
$ cd ./api-demo
$ npm run build
$ npm run simple
$ npm run advanced

To use eslint-plugin-tsdoc in a project using ESLint's Flat Config format, you can compose a configuration using profiles and mixins provided by tsdoc-build-rig.

This configuration applies TSDoc linting rules to all .ts and .tsx files. It requires setting tsconfigRootDir in parserOptions to ensure the TypeScript parser correctly resolves the project's type information.

const nodeTrustedToolProfile = require('tsdoc-build-rig/includes/eslint/flat/profile/node-trusted-tool');
const friendlyLocalsMixin = require('tsdoc-build-rig/includes/eslint/flat/mixins/friendly-locals');

module.exports = [
  ...nodeTrustedToolProfile,
  ...friendlyLocalsMixin,
  {
    files: ['**/*.ts', '**/*.tsx'],
    languageOptions: {
      parserOptions: {
        tsconfigRootDir: __dirname
      }
    }
  }
];