TypeScript Comments

1. The Need for Doc Comments
2. Use TSDoc to Generate API Documentation in TypeScript

This article is about doc comments in TypeScript.

The Need for Doc Comments

The doc comments can be seen in most programming languages. Its main purpose is to generate documentation for the given codebase.

We use JavaDoc to generate the documentation in Java, and JSDoc is the API documentation generator for JavaScript. The TypeScript uses TSDoc to generate its API documentation.

Use TSDoc to Generate API Documentation in TypeScript

The TSDoc is a specification that tells programmers how to comment on their codebase. So that tools can generate API documentation and create metadata for the TypeScript codebase.

The Microsoft TypeScript team maintains the TSDoc specification. In JSDoc, we need to use the annotations to specify the types explicitly.

Since TypeScript is a typed language, we do not need to use annotations in TSDoc, and it helps generate more informative documentation without any hassle.

TSDoc comments start with two asterisks, as shown in the following.

/**
*
*
*/

Also, it provides an @ annotation mark to specify special information like parameters, return types, and many more, as shown in the following.

export class Square {
    /**
     * @Returns the area of the given square.
     *
     * @param width  - width of the square
     * @param height - the height of the square
     * @returns The multiplication of `width` and `height`.
     */
    static calculateArea(width: number, height: number): number {
      return width * height;
    }
  }

Use Visual Studio Code to Generate API Documentation

The doc comment started with two asterisks and continues. The @Returns, @param annotations have given additional information regarding the codebase.

We can use Visual Studio Code to view the generated API documentation for the calculateArea function.

Use TypeDoc to Convert TSDoc Comments to HTML Documentation

The TSDoc comments can be used to generate HTML documentation too. Then we need to use the TypeDoc utility tool to convert TSDoc comments to rendered HTML documentation.

First, it is mandatory to install typedoc, as shown below.

npm install --save-dev typedoc

Then we can easily generate the HTML documentation using the typedoc command-line utility.

typedoc --out docs .

Different tools can use TSDoc comments in your TypeScript code and parse those to generate API documentation, HTML documentation, and other useful information regarding the codebase.