最近要為公司項(xiàng)目做javaScript API人乓，在網(wǎng)上找了幾個(gè)生成工具，JSDoc和YUIDoc好像很不錯(cuò)筑煮。我選用JSDoc制作，用node部署后使用起來很方便粤蝎。由于是剛開始學(xué)真仲，所以很多地方弄不清楚，比如jsdoc的命名空間/路徑初澎，還有對es6的支持秸应，getter/setter怎么寫等等。希望了解的同學(xué)幫忙解答~~恩謝
安裝
jsdoc
確保安裝了node后碑宴，輸入命令 ? ?
npm i jsdoc ?-g?
IDE插件
sublime 安裝插件 ?DocBlockr?
vscode ?安裝 ?add jsdoc comments
方便自動生成注釋
此外软啼，安裝JSDoc的ES6支持插件? jsdoc-export-default-interop
$ npm i ?jsdoc-export-default-interop --save-dev
docstrap
由于JSDoc默認(rèn)的文檔模板比較單調(diào)，而docstrap提供了14+種bootstrap風(fēng)格的模板延柠，因此建議下載docstrap
npm i ink-docstrap
下載完成祸挪，進(jìn)入到docstrap目錄安裝一下依賴包 npm install
移除google字體，防止頁面卡頓：
打開docstrap\template\static\styles ,將引用的google字體內(nèi)容刪除
@import url("https://fonts.googleapis.com/css?family=Roboto:400,500");
指定模板：在 jsdoc 的配置文件conf.json 下的 template 選項(xiàng) 配置為 docstrap/template 即可?
如果要手動修改模板樣式：修改文件 docstrap\template\tmpl\details.tmpl
使用
1.新建配置文件conf.json ?
為了養(yǎng)成良好的使用習(xí)慣贞间，提升工作效率贿条，建議一開始就配置好配置文件。配置文件的具體格式和參數(shù)詳見官方文檔
2.拷貝你的js到你配置文件的指定目錄
3.輸入命令
jsdoc ?c ?conf.json ?
會生成一個(gè)out文件夾增热，里面是jsdoc生成的API.
你還可以導(dǎo)入項(xiàng)目的 README.md整以，package.json，附件峻仇，教程等等公黑。
參考資料：
附上我 test 用的conf.json文件截圖
此外，tutorials 里的json目錄配置文件大概如下
對ES6的支持：
1.安裝?jsdoc-export-default-interop?插件
命令行安裝，并在conf.json里添加接口
npm install jsdoc-export-default-interop --save-dev
"plugins":["../node_modules/jsdoc-export-default-interop/dist/index"]
2. 將exports default class xx 改為 class ?xx .. module.exports = ?xx ... 或者class xx ... export default xx ..?
貼上幾個(gè)常用的塊級標(biāo)簽：
@argument?指定參數(shù)名和說明來描述一個(gè)函數(shù)參數(shù)凡蚜。
@return
@example?函數(shù)使用示例
@returns?描述函數(shù)的返回值奠骄。
@author?指示代碼的作者。
@deprecated?指示一個(gè)函數(shù)已經(jīng)廢棄番刊，不建議使用含鳞，而且在將來版本的代碼中可能會徹底刪除。要避免使用這段代碼芹务。
@see?創(chuàng)建一個(gè)HTML鏈接指向指定類的描述蝉绷。
@version?指定發(fā)布版本。
@requires?創(chuàng)建一個(gè)HTML鏈接枣抱，指向這個(gè)類所需的指定類熔吗。
@throws
@exception?描述函數(shù)可能拋出的異常的類型。
@link 創(chuàng)建一個(gè)HTML鏈接佳晶，指向指定的類桅狠。這與@see很類似，但@link能嵌在注釋文本中轿秧。?@author?指示代碼的作者中跌。（譯者注：這個(gè)標(biāo)記前面已經(jīng)出現(xiàn)過，建議去掉）
@fileoverview?這是一個(gè)特殊的標(biāo)記菇篡，如果在文件的第一個(gè)文檔塊中使用這個(gè)標(biāo)記漩符，則指定該文檔塊的余下部分將用來提供文件的一個(gè)概述。
@class?提供類的有關(guān)信息驱还，用在構(gòu)造函數(shù)的文檔中嗜暴。
@constructor?明確一個(gè)函數(shù)是某個(gè)類的構(gòu)造函數(shù)。
@type?指定函數(shù)的返回類型议蟆。
@extends?指示一個(gè)類派生了另一個(gè)類闷沥。通常JSDoc自己就可以檢測出這種信息，不過咐容，在某些情況下則必須使用這個(gè)標(biāo)記舆逃。
@private?指示一個(gè)類或函數(shù)是私有的。私有類和函數(shù)不會出現(xiàn)在HTML文檔中疟丙，除非運(yùn)行JSDoc時(shí)提供了---private命令行選項(xiàng)颖侄。
@final?指示一個(gè)值是常量值。要記住JavaScript無法真正保證一個(gè)值是常量享郊。
@ignore?JSDoc?會忽略有這個(gè)標(biāo)記的函數(shù)览祖。
