Typedoc 这是一个 TypeScript 语言的文档生成工具，类比 jsdoc。下面使用一个简单的例子来介绍一下这个工具。如果不想看文章的可以直接看下代码配置其实就能理解了~不过后面有介绍一些配置过程中的问题。栗子代码

一、准备工作

先来看一下我们最后的一个目录结构：

├── build
│   ├── App.js
│   └── App.js.map
├── gulpfile.js
├── index.html
├── package.json
├── src
│   ├── App.tsx
│   └── Home.tsx
├── tsconfig.json
├── typedoc
│   ├── README.md
│   ├── docs
│   ├── docs.json
│   └── typedoc.json
└── yarn.lock

使用到的类库主要是：

"typedoc": "^0.8.0",
"gulp-typedoc": "^2.0.2",

二、Gulp 的配置

这里分离出来 typedoc 这个类库的配置到 typedoc.json 文件。这个的好处是能够满足大家直接读取配置在任何环境下的 Options。 在这里，所有 typedoc 相关的配置和输出都放在了 typedoc 目录中，这样更好隔离开发的文件。下面看一下这个 typedoc.json 的配置，有注释说明：

{
    // 文档的标题
    "name": "TypeDoc React Demo",
    // 文档的输出路径 
    "out": "./typedoc/docs/",
    // 支持 JSX, TSX
    "jsx": true,
    // 文档结构化信息的配置 JSON
    "json": "./typedoc/docs.json",
    // 是否忽略没有导出的功能
    "excludeNotExported": false,
    // 使用一个左导航的主题，这个可以自己写样式
    "theme": "minimal",
    // 给每一份类都生成一个文件
    "mode": "file",
    "version": true,
    // 首页的内容说明
    "readme": "./typedoc/README.md"
}

为了在 .json 文件中加入注释，我这里引入了一个包（如果不这样做直接引入这样的 JSON 是会报错的）。这个包是：

"json-comments": "^0.2.1",

好吧，这些都弄完后，就开始写一个启动生成文档的 gulp 任务，这里还加上 watch，我看 issues 是 2016 提了增量编译的 feature，经过测试，其实默认是开启了这个增量编译的，后面修改某一个文件一定比第一次冷启动快。

// 这个包只需要引入一次，为了解析 JSON
require("json-comments");

var gulp = require("gulp");
var typedoc = require("gulp-typedoc");
var typedocConfig = require("./typedoc/typedoc.json");

gulp.task("typedoc", function() {
    return gulp
        .src(["src/**/*.tsx"])
        // .pipe(typedoc(typedocConfig));
        .pipe( typedoc(JSON.parse(JSON.stringify(typedocConfig))) );
});

gulp.task("watch:typedoc", ["typedoc"], function () {
    gulp.watch("src/**/*.tsx", ["typedoc"]);
});

在这里的配置需要注意的是注释掉的：.pipe(typedoc(typedocConfig));

没有像那样写是因为 gulp-typedoc 这个库在 watch 的时候会给我报一个错误，我估计是解析生成的问题，所以经过测试，使用 typedoc(JSON.parse(JSON.stringify(typedocConfig))) 这种方式或者直接把配置写入这里都是可以避免的。

如果使用注释方式的报错信息是： Error in plugin 'gulp-typedoc' Message: You must either specify the 'out' or 'json' option.

最后在 package.json 中配置 gulp watch:typedoc，然后启动就能够生成一个 API 网站了，用起来还是蛮方便的，不过还有一些问题：

1. TypeScript 的版本是与 typedoc 这个库绑定的，如果要选用项目的 ts 版本有一些方案，不过暂时现在没发现一个更好的。
2. 识别注释成文档现在是只识别多行注释 /**/
3. 对于注释的 @ 支持有限，如果不支持的 @ 默认是识别成一个 tag 的意思写入到文档中。

扫码关注w3ctech微信公众号