TypeDoc Tutorial

TypeDoc is an API document generator for TypeScript. It extracts comments in code and converts them into HTML API documentation. A good module must have a good API documentation, so that developers know how to use your module. This article will explain how to use TypeDoc in a project and how to use TypeDoc to write API documentation in code.

Generating TypeDoc API Documentation

First of all, please create a Node.js project with TypeScript. If you are not familiar with how to set up, you can read the following article first.

• • Node.js

How to Setup a Node.js Project with TypeScript

• ByWayne
• 17/09/2020

Install TypeDoc module into your project.

project % npm install typescript --save-dev

Assume that the code is all in the src/ directory. Use the following command to generate API documentation to docs/ directory based on the code under src/.

project % npx typedoc --out docs src

We can also add this command to package.json.

{
  "name": "TypedocExample",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "docs": "npx typedoc --out docs src"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "typedoc": "^0.19.2",
    "typescript": "^4.0.3"
  }
}

Then use the following command to generate API documentation.

project % npm run docs

Writing TypeDoc Comments

TypeDoc does not support all JSDoc tags, because TypeScript compiler can infer information from TypeScript type declaration. However, if you use JSDoc tags that TypeDoc does not support in comments, TypeDoc will extract these tags into API documentation as well.

TypeDoc currently understand the following tags.

@link <symbol>

@link can generate symbol links in API documents.

/**
 * {@link Vehicle} or {@linkplain Vehicle} or [[Vehicle]]
 */
export class Bus implements Vehicle {}

/** Vehicle */
interface Vehicle {
    price: number;
}

You can also specify link text.

/**
 * The {@link Vehicle | Vehicle interface}
 * The [[Vehicle | Vehicle interface]]
 */
export class Bus implements Vehicle {}

@param <param name>

@param documents function parameters.

/**
 * @param productName Name of product
 * @param quantity Number of product to buy
 */
function buy(productName: string, quantity: number): number {}

Unlike @param in JSDoc, you don’t need to write parameter’s type in front of parameter name, because the TypeScript compiler will infer it from code.

@typeParam <param name>

@typeParam documents generic parameters.

/**
 * @typeParam T Type of parameter
 */
function convertToString<T>(obj: T): string {
}

@return(s)

@return/@returns documents return value.

/**
 * @return Total amount
 */
function buy(productName: string, quantity: number): number {}

@hidden / @ignore

TypeDoc will include all classes or functions into API documentation. Even if you don’t comment on those, TypeDoc will infer them for you. If you have a function that you don’t want to appear in API documentation, that will be a problem. @hidden and @ignore can make TypeDoc ignore these codes.

/**
 * @ignore
 */
function doSomething() {}

@internal

@internal and @ignore/@hidden are very similar. The difference is that TypeDoc will ignore these codes only when you pass TypeScript compiler –stripInternal flag.

/**
 * @internal
 */
function doSomething() {}

Conclusion

Compared to JSDoc, TypeDoc is quite concise. If variable names or function names are good, you don’t even need to comment on them. TypeDoc will still extract them in API documentation for you. In addition, if you have to use some JSDoc tags, TypeDoc will also copy these.