@microsoft/tsdoc vs typedoc vs jsdoc | Documentation Generation Tools

Package	Downloads	Stars	Size	Issues	Publish	License

@microsoft/tsdoc	6,081,389	4,895	2.3 MB	148	7 days ago	MIT
typedoc	2,416,624	8,284	2.15 MB	8	a month ago	Apache-2.0
jsdoc	2,061,309	15,352	1.47 MB	452	a month ago	Apache-2.0

Package

Downloads

Stars

Size

Issues

Publish

License

@microsoft/tsdoc

6,081,389

4,895

2.3 MB

148

7 days ago

MIT

typedoc

2,416,624

8,284

2.15 MB

a month ago

Apache-2.0

jsdoc

2,061,309

15,352

1.47 MB

452

a month ago

Apache-2.0

TypeScript Support

@microsoft/tsdoc:
@microsoft/tsdoc is designed specifically for TypeScript, providing a framework for writing and parsing documentation comments that are type-aware. It helps enforce best practices in documentation for TypeScript projects.
typedoc:
typedoc is built for TypeScript and fully utilizes its type system to generate documentation. It provides rich type information, including interfaces, classes, and generics, making it the best choice for TypeScript projects.
jsdoc:
jsdoc supports TypeScript to some extent, especially with the use of the --typescript flag. However, its primary focus is on JavaScript, and it may not fully leverage TypeScript's type information without additional configuration.

Customization

@microsoft/tsdoc:
@microsoft/tsdoc provides a structured approach to documentation but is not a documentation generator itself. It focuses on defining a standard for TSDoc comments, which can be implemented by other tools for customization.
typedoc:
typedoc allows for some customization, particularly in the theming and layout of the generated documentation. However, it is more opinionated than JSDoc, focusing on type-driven documentation.
jsdoc:
jsdoc offers extensive customization options, including the ability to create custom tags, templates, and themes. Its flexibility allows developers to tailor the documentation output to meet specific needs.

Output Formats

@microsoft/tsdoc:
@microsoft/tsdoc does not generate output formats directly. Instead, it provides a specification for TSDoc comments, which can be implemented by other tools to produce HTML, Markdown, or other formats.
typedoc:
typedoc primarily generates documentation in HTML format, with some support for Markdown. It focuses on creating a structured and navigable representation of TypeScript code.
jsdoc:
jsdoc generates documentation in HTML, Markdown, and other formats. It is highly configurable, allowing developers to choose the output format that best suits their needs.

Community and Ecosystem

@microsoft/tsdoc:
@microsoft/tsdoc is backed by Microsoft and has a growing community focused on improving TypeScript documentation standards. Its ecosystem is still developing, with tools and integrations emerging.
typedoc:
typedoc has an active community of contributors and users, particularly within the TypeScript ecosystem. It is continually evolving, with new features and improvements being added regularly.
jsdoc:
jsdoc has a large and established community with a rich ecosystem of plugins, themes, and tools. Its long history and widespread use make it a reliable choice for documentation generation.

Ease of Use: Code Examples

@microsoft/tsdoc:

@microsoft/tsdoc provides a clear and structured way to write documentation comments, but it requires integration with a documentation generator to produce output. Example of TSDoc comment:

/**
 * A simple calculator class.
 *
 * @remarks This class provides basic arithmetic operations.
 * @public
 */
class Calculator {
  /**
   * Adds two numbers.
   *
   * @param a - The first number.
   * @param b - The second number.
   * @returns The sum of the two numbers.
   * @example
   * const calc = new Calculator();
   * const sum = calc.add(2, 3);
   * console.log(sum); // 5
   */
  add(a: number, b: number): number {
    return a + b;
  }
}

typedoc:

typedoc is straightforward to use for TypeScript developers, as it leverages TypeScript's type system. Example of TypeDoc comment:

/**
 * A simple calculator class.
 *
 * @class
 * @classdesc This class provides basic arithmetic operations.
 * @example
 * const calc = new Calculator();
 * const sum = calc.add(2, 3);
 * console.log(sum); // 5
 */
class Calculator {
  /**
   * Adds two numbers.
   *
   * @param a - The first number.
   * @param b - The second number.
   * @returns The sum of the two numbers.
   */
  add(a: number, b: number): number {
    return a + b;
  }
}

jsdoc:

jsdoc is easy to use, especially for those familiar with JavaScript. It uses a simple comment-based syntax to generate documentation. Example of JSDoc comment:

/**
 * A simple calculator class.
 *
 * @class
 * @classdesc This class provides basic arithmetic operations.
 * @example
 * const calc = new Calculator();
 * const sum = calc.add(2, 3);
 * console.log(sum); // 5
 */
class Calculator {
  /**
   * Adds two numbers.
   *
   * @param {number} a - The first number.
   * @param {number} b - The second number.
   * @returns {number} The sum of the two numbers.
   */
  add(a, b) {
    return a + b;
  }
}

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