TypeDoc 教學

Photo by Berkay Gumustekin on Unsplash
Photo by Berkay Gumustekin on Unsplash
TypeDoc 是一個 TypeScript 的 API 文件產生器。它將程式碼中的註解提取出來,並轉換成網頁 API 文件。本文章將介紹如何在專案中使用 TypeDoc,以及如何用 TypeDoc 在程式碼中撰寫 API 文件。

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

產生 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 可以在 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 也會複製這些註解。

發佈留言

發佈留言必須填寫的電子郵件地址不會公開。 必填欄位標示為 *

You May Also Like
Photo by Rayia Soderberg on Unsplash
Read More

Webpack 新手教學

Webpack 是什麼呢?就如它的官網所言,它是可以用來打包 (Bundle) scripts、styles、images、assets。在 Bundle 的過程中,它會解析這些檔案與模組之間的依賴關係,最後輸出靜態的檔案。在 Runtime 時,不需要再安裝第三方模組。
Read More
Photo by Harley-Davidson on Unsplash
Read More

如何建立 Node.js CLI 專案

Node.js 讓我們可以用 JavaScript 開發命令列應用程式 (CLI, Command-line interface, application) 或是服務器端應用程式 (Server side application)。本篇會介紹如何建立一個 Node.js CLI 專案。
Read More