typedoc typescript 註釋文檔生成器

image.png

安裝

cnpm i --dev typedoc
or
yarn add --dev typedoc

使用

// 指定生成對象
typedoc file.ts
// 指定輸出目錄
typedoc --out ./docs

默認將在根目錄生成文檔目錄 /docs

註釋規則

/** * 首行功能名稱 * @param 參數說明 * @typeParam 類型參數 * @return(s) 返回說明 * @event 事件說明 * @hidden @ignore 跳過 * @interval 內部代碼，若是配置了 excludeInternal 該段將被忽略 * @category 反射分組 */

// 其餘
/** * @prop 屬性 * @example 使用例子 */


// 代碼塊,使用markdown語法
/** * ``` typescript * class Man { ... } * ``` */
### 註釋例子
/** * 文本節點 * @param tag 節點內容 * @return 返回文本節點字符 * @example * ``` typescript * 1. textTag(null) * => '' * * 2. textTag(undefined) * => '' * * 3. textTag({ name: 'coco' }) * => ` * { * name: 'coco' * } * ` * * 4. textTag('container') * => 'container' * * 5. textTag(() => {...}) * => '() => {...}' * ``` */

配置項目

tsconfig

使用 tsconfig 配置文件規則

typedoc --tsconfig </path/to/tsconfig.json>

entryPoints

入口地址

$ typedoc a b
# or
$ typedoc --entryPoints a --entryPoints b

exclude

排除規則，排除不須要生成的文件

typedoc --exclude "**/*+(index|.spec|.e2e).ts"

excludePrivate

不生成類的 Private 屬性文檔

typedoc --excludePrivate

excludeProtected

不生成 類的 Protected 屬性文檔

typedoc --excludeProtected

excludeInternal

排除內部信息

typedoc --excludeInternal

media

注入多媒體文件地址

typedoc --media <path/to/media/>

includes

注入其餘文檔地址, 例如 markdown 文件

typedoc --includes <path/to/includes/>

out

文檔輸出目錄

typedoc --out <path/to/documentation/>

json

輸出 json 文件

typedoc --json <path/to/out-file.json>

emit

typedoc --emit

theme

設置主題

typedoc --theme <default|minimal|path/to/theme>

highlightTheme

設置高亮主題

typedoc --highlightTheme dark-plus

watch

監聽生成

typedoc --watch

使用配置文件

// typedoc.config.json
{
  "entryPoints" : "./src",
  "exclude": "**/__test__/*.ts",
  "out": "./docs"
}
// package.json
"doc:build": "typedoc --options ./typedoc.config.json",

配合構建工具使用

Gulp

// 安裝插件
npm install --save-dev gulp-typedoc
// 添加任務
var typedoc = require("gulp-typedoc");
gulp.task("typedoc", function () {
  return gulp.src(["src/**/*.ts"] // 入口).pipe(
    typedoc({
      // 文檔生成配置
      out: "docs/",
      name: "My project title",
    })
  );
});

參考

官方文檔

本文同步分享在 博客「直立猿」（JianShu）。
若有侵權，請聯繫 support@oschina.cn 刪除。
本文參與「OSC源創計劃」，歡迎正在閱讀的你也加入，一塊兒分享。