为TypeScript项目自动生成 api doc 文档

介绍

如果用的是原生JS开发，那么生成文档大家有很多选择，像jsdoc这种很常用的工具，网上很好找资料，但是对于Ts项目，先后找了很多，都不是很理想，最终在Stack Overflow上找到这个工具 TypeDoc，目前还是比较好用。对于生成Typescript项目的 api文档方式与jsdoc类似。

TypeDoc生成文档时会运行TypeScript编译器，并从生成的编译器符号中提取类型信息，因此，我们是不必在注释中包含像参数类型这些元数据的，TypeDoc将自动检测TypeScript特定的元素，如类，枚举或属性类型以及访问修饰符。

TypeDoc使用标记MarkDown标记解析器和HighlightJS来突出显示标记部分内的代码块，在TypeScript中的所有注释都被解析为MarkDown格式因此，我们可以在注释中使用MarkDown语法。当然我们也可以，您可以使用CSS类来自定义样式。

TypeDoc能解析的注释注释必须写在/** ... */之间，目前只支持@param 和@return(s)标签。TypeDoc生成文档时会运行TypeScript编译器自动识别变量元数据，所以像jsdoc中的大部分@标签在TypeScript中是可以忽略的，如果你写了其他标签，所有其他标签将被呈现为定义列表，它们是不会被忽略的。

用法

可以配合 webpack插件 或者 Grunt插件 、 gulp插件 使用，也可以单独使用

安装

npm install typedoc --save-dev

单独使用

typedoc --out path/to/documentation/ path/to/typescript/project/

参数

--out  指定输出位置 
--name  指定生成的文档的title名称，会显示在文档logo处 
--readme  指定reamme.md的位置，用于生成首页，不指定则文档不会有首页  
--module  指定模块生成方式：
--target  指定生成文档的js版本  
--exclude  排除指定文件  
--theme  指定文档主题样式，可以使用内置的或自定义主题  
--includeDeclarations  解析.d.ts类型声明文件
--externalPattern  定义应该被认为是外部的文件的模式  
--excludeExternals  阻止生成的文档外部解析的TypeScript被记录
--hideGenerator   请勿在页面末尾打印TypeDoc链接。
--verbose   生成文档时打印详细的日志
--gaID    设置Google Analytics跟踪ID并激活跟踪代码
--gaSite    设置Google Analytics的网站名称。默认为auto