文章目录
  1. 1. TypeDoc
  2. 2. 为什么不使用JSDoc?
  3. 3. 使用小记
    1. 3.1. 1. 安装
    2. 3.2. 2. 使用
    3. 3.3. 3. 配置项
    4. 3.4. 4. 其它方式
  4. 4. 小结

由于目前主要前端语言由 JavaScript 切换到了 TypeScript,所以原先用的 JSDoc 工具也用不了了,虽说 JSDoc 官方也在积极适配TypeScript,但始终产品不能等工具。何况不是核心的文档功能。

于是上Github上找了一下,很快发现了以下项目:

TSDoc
typescript-docs
ts2jsdoc

Star 只有几十不说,安装下来,发现功能粗糙,很多基本的应该有的功能很难进行定制,生成效果和预期差距很大。

TypeDoc

这些项目的理念是基于 JSDoc 或是自己实现一个简单的 JSDoc 来实现文档化,于是换了换思路,终于找到了神器 typedoc

官网 : http://typedoc.org

GitHub : https://github.com/TypeStrong/typedoc

简单的用了下,虽然也是肤浅的使用,但认定它应该就是 TypeScript 里面的 jsdoc了。

为什么不使用JSDoc?

最重要的一点 :TypeScript 本身已经是强类型语言了,没有必要退化弱类型的 JavaScript 。

TypeDoc 使用的是 JavaDoc 而不是 JSDoc,由于 TypeScript 更像 Java 而不像 JavaScript 所以使用了更为简单的 JavaDoc 这样一样,Jsdoc里面的很多标签也就没有什么意义了。

本身来说,使用频率最高的 @param @returns 等写法,用法基本相同,切换到 JavaDoc 也没什么太大问题,重要的是,你再也不需要 @typedef 之类的标签了,学习成本微乎其微。

JavaDoc 说明: http://www.xdnote.com/javadoc/

名称 作用 备注
@param 参数描述 仅供类、接口、方法注释时使用。同一个注释块可同时出现多个param描述。
@return 返回描述 仅供方法注释时使用。除void方法外其它所有方法必须有一个return描述。
@throws 异常描述 零到多个。
@exception 异常描述 零到多个。
@author 作者 类和接口注释中必须有。可有零到多个。
@version 版本描述 类和接口注释中必须有。零或一个。
@see 参考描述 可有零到多个。
@since 起始版本 只有一个。
@serial 序列化描述 @serialField@serialData,可有多个
@deprecated 废除标志 最多一个。

使用小记

1. 安装

1
npm install -g typedoc

2. 使用

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

虽然可以使用命令行,但一般都是与 gulp webpack 等工具集成使用,以 gulp 为例:安装插件 gulp-typedoc

1
npm install --save-dev gulp-typedoc

配置任务

1
2
3
4
5
6
7
8
9
10
11
12
var typedoc = require("gulp-typedoc");
gulp.task("typedoc", function() {
return gulp
.src(["src/**/*.ts"])
.pipe(typedoc({
module: "commonjs",
target: "es5",
out: "docs/",
name: "Title"
}))
;
});

3. 配置项

其中 typedoc 可以传配置参数,详细的参数如下:

参数 类型 说明
out string 输出目录
module string 模块引入方式,可以是 commonjs, amd, system, umd
target string ES3(默认), ES5, ES6
name string 项目标题
theme string 皮肤可以是 default or minimal or 一个路径,更多资料
readme string readme文件,markdown文件的相对地址
includeDeclarations boolean 是否包含 .d.ts 文件
excludeExternals boolean 是否排除外部引入的模块
excludePrivate boolean 是否排除 private 修饰的相关字段方法
excludeProtected boolean 是否排除 protected 修饰的相关字段方法
hideGenerator boolean 隐藏页底的全局链接
version boolean 显示 typedoc 版本
help boolean 显示帮助信息
gaID string 如果有 Google Analytics 的跟踪ID,可以设置
includes string 包含文件
exclude string 排除文件
media string 包含媒体,比如LOGO等等

4. 其它方式

Webpack :https://www.npmjs.com/package/typedoc-webpack-plugin

Gulp :https://www.npmjs.org/package/gulp-typedoc/

Grunt :https://www.npmjs.org/package/grunt-typedoc

小结

由于使用不深,遇到一些坑也填了一些坑,总之,目前 TypeDoc 虽然并不完美,但目前选择也不太多,如果你使用 TypeScript 可以考虑使用它做为你的首选文档工具!

文章目录
  1. 1. TypeDoc
  2. 2. 为什么不使用JSDoc?
  3. 3. 使用小记
    1. 3.1. 1. 安装
    2. 3.2. 2. 使用
    3. 3.3. 3. 配置项
    4. 3.4. 4. 其它方式
  4. 4. 小结