簡單說函喉，用JSDoc寫開發(fā)文檔就是寫注釋，只是在書寫的時候要把它們按照規(guī)范工整的寫出來，這樣即可達到注釋的目的又能順便地讓JSDoc生成規(guī)范的文檔取董，兩全其美。這樣想事情就簡單多了不是嗎无宿？
怎么做?
我這里只講在node.js平臺下的操作步驟茵汰。
全局安裝JSDoc依賴包：
npm i jsdoc -g
隨便寫一個帶有JSDoc注釋的js文件吧：
/**
* JSDoc Demo File
* see more link to <a >blog.pagegaga.com</a>
* @author Warren <aliang_ok@sina.com>
* @copyright Warren 2016
*/
/**
* Say hello.
* @param {string} str - Anything what you want to say.
*/
var app=function(str){
alert('hello');
}
然后就能在項目根目錄下執(zhí)行命令，對要生成文檔的文件做解析了：
jsdoc ./
上面這段命令是說對項目根目錄（不包括子目錄）下所有文件做解析孽鸡，這樣做的結果是JSDoc解析指定目錄所有包含以JSDoc規(guī)范書寫注釋的文件蹂午，并在默認目錄（./out）下生成可供瀏覽器訪問的html文件及相關依賴（包括樣式、字體彬碱、腳本等）文件豆胸。執(zhí)行完成后，就可以在項目根目錄里找到./out/index.html文件雙擊預覽了堡妒。
JSDoc 提供了很多命令行參數(shù)配乱，可以看官方文檔關于命令行相關的說明，這里簡單舉個例子：
我們可以執(zhí)行npm i docdash --save-dev安裝一個第三方的主題包皮迟，然后執(zhí)行如下命令：
jsdoc ./app.js -d ./doc -t ./node_modules/docdash
結果是搬泥，JSDoc把app.js中的注釋生成文檔并放到了指定目錄（./doc）下，同時生成的文檔套用了docdash主題伏尼。
在命令行里執(zhí)行命令每次都要重寫一遍那些冗長的配置參數(shù)很麻煩忿檩，不怕，JSDoc可以引用外部配置文件讓事情一勞永逸：
在項目目錄下新建一個名為jsdoc.cfg.json的配置文件爆阶，然后以JSON格式填寫如下內容到這個配置文件中:
{
"source":{
"include":[".","./server/"],
"exclude":["./node_modules/"]
},
"opts":{
"template":"node_modules/docdash",
"encoding":"utf8",
"destination":"./jsdoc/",
"readme":"readme.md"
}
}
關于這些配置項的解釋燥透，可以在官網(wǎng)找到。保存后辨图，再執(zhí)行如下命令：
jsdoc -c jsdoc.cfg.json
這樣班套，JSDoc就會按照指定的配置文件中的配置信息來處理文檔了。
了解清楚如何生成文檔故河，剩下的問題就是怎么寫規(guī)范的注釋才能生成像樣的開發(fā)文檔了吱韭。
怎么寫？
JSDoc注釋以/**開頭*/結尾鱼的，并且每一行開頭都有一個*理盆。在注釋段內通過以@開頭的標簽為代碼提供注解，JSDoc根據(jù)這些標簽來組織文檔結構凑阶，套用樣式最終生成文檔猿规。我們在這里只舉幾個常用的例子：
每個模塊都可以有這樣的標簽：
/**
* description
* description more
* @author author name <email>
* @copyright copyright information
*/
- description 用來描述代碼段，其中可以插入html元素宙橱，比如一個a鏈接姨俩，
-
@author可以注明該代碼塊的作者蘸拔， -
@copyright用來聲明版權。
function：
/** function description
* @param {type} paramName - description
* @returns {type} description
*/
-
@param用來描述函數(shù)參數(shù)哼勇，{type}是一個內聯(lián)標簽都伪，用來注明該參數(shù)的類型（比如string、object积担、number），-后面再寫該參數(shù)的描述文字猬仁； -
@returns用來標注該函數(shù)最終返回什么類型的值并加以說明帝璧。
模塊：
/** module description
* @module
*/
@module 后面可以跟模塊名，如果不寫湿刽，JSDoc會自動取名的烁。
JSDoc提供了豐富的標簽，官網(wǎng)文檔為我們做了詳細講解诈闺，務必去閱讀下渴庆。
代碼用法列舉：
可以用@example為代碼添加應用案例，以實際用例說明代碼的用法：
/** description
* @example
* app('hello');//調用方法
*/
更多
上面看起來很簡單對嗎雅镊？然而它可以做更多襟雷！通過JSDoc插件機制可以支持解析并嵌入markdown、通過解析node.js的package.json構建文檔的目錄結構等諸多功能讓文檔變得更飽滿仁烹。
想要讓項目工程化進展得更順溜耸弄，怎能少了JSDoc這個利器呢？
