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 可以傳配置參數，詳細的參數如下：
| 參數 | 類型 | 說明 |
|---|---|---|
| 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 | 包含媒體，應該是一個文件夾的名字，會包含文件夾下的圖片等各種媒體文件（需要使用  引入） |
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/