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源创计划”，欢迎正在阅读的你也加入，一块儿分享。