TypeDoc 教學

TypeDoc 是一個 TypeScript 的 API 文件產生器。它將程式碼中的註解提取出來，並轉換成網頁 API 文件。好的模組必須要有好的 API 文件，這樣開發者才知怎麼使用你的模組。本文章將介紹如何在專案中使用 TypeDoc，以及如何用 TypeDoc 在程式碼中撰寫 API 文件。

產生 TypeDoc API 文件

首先，請先建立一個 TypeScript 的 Node.js 專案。如果不熟悉怎麼建立的話，可以先閱讀下面的文章。

• • Node.js

如何建立 Node.js + TypeScript 專案

• ByWayne
• 03/08/2020

安裝 TypeDoc 模組到專案裡。

project % npm install typescript --save-dev

假設專案中的程式碼都在 src/ 目錄下。用下面的指令，根據 src/ 下的程式碼，產生 API 文件到 docs/ 目錄。

project % npx typedoc --out docs src

我們也可以將這指令新增到 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"
  }
}

之後用下面的指令就可以產生 API 文件了。

project % npm run docs

撰寫 TypeDoc 註解

TypeDoc 沒有支援所有 JSDoc 的 tags，因為 TypeScript 編譯器可以從 TypeScript 的型態宣告中推導出很多資訊。不過，如果你在註解中使用到 TypeDoc 沒有支援的 JSDoc 的 tags 的話，TypeDoc 也會將這些 tags 擷取到 API 文件中。

以下介紹 TypeDoc 有支援的 tags。

@link <symbol>

@link 可以在 API 文件中產生參照連結。

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

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

也可以指定連結上的字。

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

@param <param name>

@param 註解函式的參數。

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

與 JSDoc 的 @param 不同的是，你不需要在參數名前面寫上參數的型態，因為 TypeScript 編譯器會從程式碼中推導出來。

@typeParam <param name>

@typeParam 註解範型的型態參數。

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

@return(s)

@return/@returns 註解回傳值。

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

@hidden / @ignore

TypeDoc 會將所有的類別、函式等都收入到 API 文件中。即使你沒有對那些下註解，TypeDoc 會替你推導。如果你有個函式不想出現在 API 文件中，那就會有問題了。@hidden 和 @ignore 可以讓 TypeDoc 忽略這些程式碼。

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

@internal

@internal 和 @ignore/@hidden 是相同的作用。差別在於，只有當你有給 TypeScript 編譯器 –stripInternal 選項時，TypeDoc 才會忽略這些程式碼。

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

結論

比起 JSDoc，TypeDoc 使用起來相當地簡潔。如果變數名稱或是函數名稱取的好的話，你甚至不需要為它們撰寫註解。而 TypeDoc 還是會為你將它們收到 API 文件中。此外，如果你有需要某些 JSDoc 的 tags，TypeDoc 也會複製這些註解。