一、javascript注釋規范
我們在編寫javascript文件的時候，一般會添加一些注釋。例如一些文件、類、方法和屬性都應該用合適的標記和類型進行注釋。這里不但方便我們的閱讀，也能養成一個好的習慣。更大的好處是，我們可以根據這些注釋生成幫助文檔。如下就是一個比較規范的javascript注釋例子。
/**
* MyClass類
* @class MyClass
* @constructor
*/
function MyClass() {
/**
* a屬性
* @property a
* @type int
**/
var a = 0;
/**
獲得A的值
@memberof MyClass
@method getA
@param returnType {int} 要設置的值
@example ele.setReturnType('0000');
**/
function setA(a) {
this.a = a;
}
/**
設置A的值
@memberof MyClass
@method getA
@param returnType {int} 要設置的值
@example ele.setReturnType('0000');
**/
function getA() {
return a;
}
}
二、JSDoc 3
JSDoc 3是一個生成為Javascript生成API文檔的工具。下載地址為：https://github.com/jsdoc3/jsdoc 。使用JSDoc 3 我們需要有Node.js環境。Node.js安裝好之后，我們可以通過如下命令，可以按照最好的alpha版本：
npm install jsdoc@"<=3.3.0"
在cmd輸入該命令，回車。當顯示如下結果的時候，說明JSDoc 3已經安裝完成
不過此時JSDoc 3並沒被添加到系統環境下。此時我們可以在cmd中進入C:\Users\user\node_modules\.bin該目錄下，輸入jsdoc -v，會顯示安裝的版本。我們將要生成文檔的js文件拷貝到這個文件夾下，在cmd里面輸入命令jsdoc test.js,目錄下會生成out文件目錄，該目錄里面就是生成的API 文檔。
文件上面的代碼保存到test.js中，生成的API文檔如下圖所示
三、JSDoc 3相關配置了解
1、我們使用JSDoc生成javascriptAPI文檔，必須要使用規范的注釋。該注釋可以參考 http://usejsdoc.org/.
2、為多個文件生成幫助文檔
此時我們可以配置C:\Users\user\node_modules\jsdoc目錄下的conf.json.EXAMPLE文件。為這個文件source里面添加一行如下圖所示：
將要生成API文檔的JS文件名稱配置進入，然后將這寫配置了的JS文件拷貝到C:\Users\user\node_modules\.bin這個文件夾里面。在cmd里面運行jsdoc，即可生成API文檔。
注意：可能我們生成的API文檔會有亂碼，因為JSDoc 3生成的API文檔默認是使用utf8編碼格式生成文檔。當我們的js文件內容不是使用utf8的時候，就會產生亂碼。此時我們將JS文件都改成utf8編碼，然后重新生成幫助文檔，這樣就不會有編碼問題。