什麼是 JSDoc

JSDoc 是一個根據 JavaScript 檔案中註釋資訊，生成 JavaScript 應用程式或模組的API文件的工具。你可以使用 JSDoc 標記如：名稱空間，類，方法，方法引數等。從而使開發者能夠輕易地閱讀程式碼，掌握程式碼定義的類和其屬性和方法，從而降低維護成本，和提高開發效率。

JSDoc 註釋規則

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 註釋的內容，可參考下面的連結。

JSDoc 文件