TypeDoc 是一個 TypeScript 的 API 文件產生器。它將程式碼中的註解提取出來,並轉換成網頁 API 文件。好的模組必須要有好的 API 文件,這樣開發者才知怎麼使用你的模組。本文章將介紹如何在專案中使用 TypeDoc,以及如何用 TypeDoc 在程式碼中撰寫 API 文件。
Table of Contents
產生 TypeDoc API 文件
首先,請先建立一個 TypeScript 的 Node.js 專案。如果不熟悉怎麼建立的話,可以先閱讀下面的文章。
安裝 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 也會複製這些註解。