文章目录
  1. 1. TypeDoc
  2. 2. 为什么不使用JSDoc?
  3. 3. 使用小记
    1. 3.1. 1. 安装
    2. 3.2. 2. 使用
    3. 3.3. 3. 配置项
    4. 3.4. 4. 插入自己的内容
    5. 3.5. 5. 其它方式
  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 标签

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// 1. 在JSDoc里面的写法

/**
* @param {string} name 姓名
* @param {number} age 年龄
*/


// 2. 在TypeDoc里面的写法
/**
* @param name 姓名
* @param age 年龄
*/

在TypeDoc里面,很多类型定义的标签你再也不需要了,比如 @typedef 等,标签的使用方法更为简单。

名称 作用 备注
@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 文件,如果你的项目是javascript写的,可以使用声明文件的方式来支持TypeScript并生成文档
excludeExternals boolean 是否排除外部引入的模块
excludePrivate boolean 是否排除 private 修饰的相关字段方法
excludeProtected boolean 是否排除 protected 修饰的相关字段方法
hideGenerator boolean 隐藏页底的全局链接
version boolean 显示 typedoc 版本
help boolean 显示帮助信息
gaID string 如果有 Google Analytics 的跟踪ID,可以设置
exclude string 排除文件
includes string 包含文件,应该是一个文件夹的名字,会将下面所有的md文件包含进来(需要使用 [[include:document.md]] 引入)
media string 包含媒体,应该是一个文件夹的名字,会包含文件夹下的图片等各种媒体文件(需要使用 ![logo](media://logo.png) 引入)

4. 插入自己的内容

刚才说了 includes media 两个参数。

5. 其它方式

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, 并且对于很细节的质量要求不高,可以考虑使用它做为你的首选文档工具!

附链接地址,前面是本人写的(时代久远),后面是官方文档(建议):

JavaDoc 说明: http://www.xdnote.com/javadoc/ https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDJGIJB

JSDoc 说明: http://www.xdnote.com/javascript-doc/ http://usejsdoc.org/

文章目录
  1. 1. TypeDoc
  2. 2. 为什么不使用JSDoc?
  3. 3. 使用小记
    1. 3.1. 1. 安装
    2. 3.2. 2. 使用
    3. 3.3. 3. 配置项
    4. 3.4. 4. 插入自己的内容
    5. 3.5. 5. 其它方式
  4. 4. 小结