TypeScript 文档化工具: typedoc

http://www.xdnote.com/typedoc/

由于目前主要前端语言由 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 可以传配置参数,详细的参数如下:

参数类型说明
outstring输出目录
modulestring模块引入方式,可以是 commonjs, amd, system, umd
targetstringES3(默认), ES5, ES6
namestring项目标题
themestring皮肤可以是 default or minimal or 一个路径,更多资料
readmestringreadme文件,markdown文件的相对地址
includeDeclarationsboolean是否包含 .d.ts 文件,如果你的项目是javascript写的,可以使用声明文件的方式来支持TypeScript并生成文档
excludeExternalsboolean是否排除外部引入的模块
excludePrivateboolean是否排除 private 修饰的相关字段方法
excludeProtectedboolean是否排除 protected 修饰的相关字段方法
hideGeneratorboolean隐藏页底的全局链接
versionboolean显示 typedoc 版本
helpboolean显示帮助信息
gaIDstring如果有 Google Analytics 的跟踪ID,可以设置
excludestring排除文件
includesstring包含文件,应该是一个文件夹的名字,会将下面所有的md文件包含进来(需要使用 [[include:document.md]] 引入)
mediastring包含媒体,应该是一个文件夹的名字,会包含文件夹下的图片等各种媒体文件(需要使用 ![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/

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值