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",
    })
  );
});

参考

官方文档