JSDoc 注釋規(guī)范
什么是 JSDoc
JSDoc 是一個根據 JavaScript 文件中注釋信息，生成 JavaScript 應用程序或模塊的API文檔的工具抢野。你可以使用 JSDoc 標記如：命名空間拷淘，類，方法指孤，方法參數等启涯。從而使開發(fā)者能夠輕易地閱讀代碼，掌握代碼定義的類和其屬性和方法恃轩，從而降低維護成本逝嚎，和提高開發(fā)效率。
JSDoc 注釋規(guī)則
JSDoc注釋一般應該放置在方法或函數聲明之前详恼，它必須以/ **開始补君，以便由JSDoc解析器識別。其他任何以??/*??昧互，??/***??或者超過3個星號的注釋挽铁，都將被JSDoc解析器忽略。如下所示：
/*
**一段簡單的 JSDoc 注釋敞掘。
*/
JSDoc 的注釋效果
假如我們有一段這樣的代碼叽掘，沒有任何注釋，看起來是不是有一定的成本玖雁。
functionBook(title, author){
? ? ? this.title=title;
? ? ? this.author=author;
}
Book.prototype={
? ? ? getTitle:function(){
????????returnthis.title;? ?
? ? ? },
setPageNum:function(pageNum){
? ? ? this.pageNum=pageNum;? ?
}
};
如果使用了 JSDoc 注釋該代碼后更扁，代碼的可閱讀性就大大的提高了。
/**
* Book類赫冬，代表一個書本.
* @constructor
* @param {string} title - 書本的標題.
* @param {string} author - 書本的作者.
*/
functionBook(title, author){
????this.title=title;
? ? this.author=author;
}
Book.prototype={
/**
* 獲取書本的標題
* @returns {string|*} 返回當前的書本名稱
*/
getTitle:function(){
????returnthis.title;? ?
},
/**
* 設置書本的頁數
* @param pageNum {number} 頁數
*/
setPageNum:function(pageNum){
????this.pageNum=pageNum;? ?
}
};
@constructor 構造函數聲明注釋
@constructor明確一個函數是某個類的構造函數浓镜。
@param 參數注釋
我們通常會使用@param來表示函數、類的方法的參數劲厌，@param是JSDoc中最常用的注釋標簽膛薛。參數標簽可表示一個參數的參數名、參數類型和參數描述的注釋补鼻。如下所示：
/**
* @param {String} wording 需要說的句子
*/
functionsay(wording){
????console.log(wording);
}
@return 返回值注釋
@return表示一個函數的返回值哄啄，如果函數沒有顯示指定返回值可不寫雅任。如下所示：
/*
* @return {Number} 返回值描述
*/
@example 示例注釋
@example通常用于表示示例代碼,通常示例的代碼會另起一行編寫，如下所示：
/*
* @example
* multiply(3, 2);
*/
其他常用注釋
@overview對當前代碼文件的描述咨跌。
@copyright代碼的版權信息沪么。
@author []代碼的作者信息。
@version當前代碼的版本锌半。
更多參考
如果想了解更多的 JSDoc 注釋的內容成玫，可參考下面的鏈接。
