@microsoft/tsdoc

What is @microsoft/tsdoc?

@microsoft/tsdoc is a library for parsing and analyzing TypeScript doc comments. It provides a standardized way to document TypeScript code, enabling developers to create consistent and comprehensive documentation for their projects.

What are @microsoft/tsdoc's main functionalities?

Parsing TSDoc Comments

This feature allows you to parse TSDoc comments from a string. The parser processes the comment and provides a structured representation of its content, which can be used for further analysis or documentation generation.

const tsdoc = require('@microsoft/tsdoc');

const parser = new tsdoc.TSDocParser();
const text = `/**
 * This is a summary.
 *
 * @remarks
 * Additional details go here.
 *
 * @param paramName - Description of the parameter.
 * @returns Description of the return value.
 */`;
const parserContext = parser.parseString(text);

console.log(parserContext.docComment.summarySection.toString());

Custom TSDoc Tags

This feature allows you to define and use custom TSDoc tags. By extending the TSDoc configuration, you can introduce new tags that suit your project's specific documentation needs.

const tsdoc = require('@microsoft/tsdoc');

const configuration = new tsdoc.TSDocConfiguration();
configuration.addTagDefinition(new tsdoc.TSDocTagDefinition({
  tagName: '@customTag',
  syntaxKind: tsdoc.TSDocTagSyntaxKind.BlockTag
}));

const parser = new tsdoc.TSDocParser(configuration);
const text = `/**
 * This is a summary.
 *
 * @customTag
 * Custom tag content.
 */`;
const parserContext = parser.parseString(text);

console.log(parserContext.docComment.customBlocks[0].blockTag.tagName);

Validation of TSDoc Comments

This feature allows you to validate TSDoc comments and identify any issues or inconsistencies. The parser logs messages that can be reviewed to ensure the documentation adheres to the expected standards.

const tsdoc = require('@microsoft/tsdoc');

const parser = new tsdoc.TSDocParser();
const text = `/**
 * This is a summary.
 *
 * @param paramName - Description of the parameter.
 * @returns Description of the return value.
 */`;
const parserContext = parser.parseString(text);

const messages = parserContext.log.messages;
messages.forEach(message => {
  console.log(`${message.messageId}: ${message.text}`);
});

Other packages similar to @microsoft/tsdoc

typedoc

TypeDoc is a documentation generator for TypeScript projects. It generates HTML documentation from TypeScript source files, leveraging TypeScript's type system to provide detailed and accurate documentation. Unlike @microsoft/tsdoc, which focuses on parsing and analyzing doc comments, TypeDoc is more about generating complete documentation websites.

jsdoc

JSDoc is a popular documentation generator for JavaScript and TypeScript. It uses special comments to generate HTML documentation. While JSDoc is more mature and widely used, it does not provide the same level of TypeScript-specific features and integration as @microsoft/tsdoc.

documentation

Documentation.js is a documentation generator for JavaScript and TypeScript. It supports various output formats, including HTML and Markdown. Similar to JSDoc, it focuses on generating documentation from comments but lacks the TypeScript-specific features provided by @microsoft/tsdoc.

README

@microsoft/tsdoc

This library is the reference implementation of a parser for the TSDoc syntax. Using this library is an easy way to ensure that your tool is 100% compatible with the standard.

What is TSDoc?

TSDoc is a proposal to standardize the doc comments used in TypeScript source files. It allows different tools to extract content from comments without getting confused by each other's syntax. The TSDoc notation looks pretty familiar:

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;
  }
}

Give it a try!

Check out the TSDoc Playground for a cool live demo of our parser!

API Usage

The api-demo folder on GitHub illustrates how to invoke the TSDoc parser.

A separate NPM package @microsoft/tsdoc-config is used for loading the tsdoc.json file.

Get involved

The TSDoc project is actively evolving. Please visit the website for the latest documentation, instructions for building/debugging the projects, and other resources:

https://tsdoc.org/