CommonJS 模組
概觀
為了協助您記錄 CommonJS 模組，JSDoc 3 了解 CommonJS 規範中使用的許多慣例（例如，將屬性新增到 exports 物件）。此外，JSDoc 識別 Node.js 模組 的慣例，這些慣例擴充了 CommonJS 標準（例如，將值指定給 module.exports）。根據您遵循的編碼慣例，您可能需要提供一些額外的標籤，以協助 JSDoc 了解您的程式碼。
此頁面說明如何記錄使用多種不同編碼慣例的 CommonJS 和 Node.js 模組。如果您要記錄非同步模組定義 (AMD) 模組（也稱為「RequireJS 模組」），請參閱 AMD 模組。
模組識別碼
在多數情況下，您的 CommonJS 或 Node.js 模組應包含一個獨立的 JSDoc 註解，其中包含 @module 標籤。@module 標籤的值應傳遞給 require() 函式的模組識別碼。例如，如果使用者透過呼叫 require('my/shirt') 來載入模組，您的 JSDoc 註解將包含標籤 @module my/shirt。
如果您使用沒有值的 @module 標籤，JSDoc 將嘗試根據檔案路徑猜測正確的模組識別碼。
當您使用 JSDoc 名稱路徑 從另一個 JSDoc 註解參照模組時，您必須新增前置詞 module:。例如，如果您希望模組 my/pants 的文件連結到模組 my/shirt，您可以使用 @see 標籤 來記錄 my/pants，如下所示
/**
* Pants module.
* @module my/pants
* @see module:my/shirt
*/
類似地，模組中每個成員的名稱路徑將從 module: 開始，後接模組名稱。例如，如果您的 my/pants 模組匯出 Jeans 建構函式，且 Jeans 有名為 hem 的執行個體方法，則執行個體方法的長名稱為 module:my/pants.Jeans#hem。
「exports」物件的屬性
最容易記錄直接指定給 exports 物件屬性的符號。JSDoc 會自動識別模組匯出這些符號。
在以下範例中，my/shirt 模組匯出方法 button 和 unbutton。JSDoc 會自動偵測模組匯出這些方法。
/**
* Shirt module.
* @module my/shirt
*/
/** Button the shirt. */
exports.button = function() {
// ...
};
/** Unbutton the shirt. */
exports.unbutton = function() {
// ...
};
指定給區域變數的值
在某些情況下，匯出的符號可能會指定給區域變數，然後再新增至 exports 物件。例如，如果模組匯出 wash 方法，且模組本身經常呼叫 wash 方法，您可以將模組撰寫如下
/**
* Shirt module.
* @module my/shirt
*/
/** Wash the shirt. */
var wash = exports.wash = function() {
// ...
};
在這種情況下，JSDoc 不會 自動將 wash 記錄為匯出方法，因為 JSDoc 註解出現在區域變數 wash 之前，而不是 exports.wash 之前。一種解決方法是新增 @alias 標籤，定義方法的正確長名稱。在這種情況下，方法是模組 my/shirt 的靜態成員，因此正確長名稱是 module:my/shirt.wash
/**
* Shirt module.
* @module my/shirt
*/
/**
* Wash the shirt.
* @alias module:my/shirt.wash
*/
var wash = exports.wash = function() {
// ...
};
另一種解決方法是移動方法的 JSDoc 註解，使其出現在 exports.wash 之前。此變更允許 JSDoc 偵測 wash 是由模組 my/shirt 匯出的
/**
* Shirt module.
* @module my/shirt
*/
var wash =
/** Wash the shirt. */
exports.wash = function() {
// ...
};
指定給 'module.exports' 的值
在 Node.js 模組中，您可以直接將值指定給 module.exports。此部分說明如何記錄指定給 module.exports 的不同類型值。
指定給 'module.exports' 的物件文字
如果模組將物件文字指定給 module.exports。JSDoc 會自動辨識模組只匯出此值。此外，JSDoc 會自動設定每個屬性的正確長名稱
/**
* Color mixer.
* @module color/mixer
*/
module.exports = {
/**
* Blend two colors together.
* @param {string} color1 - The first color, in hexadecimal format.
* @param {string} color2 - The second color, in hexadecimal format.
* @return {string} The blended color.
*/
blend: function(color1, color2) {
// ...
},
/**
* Darken a color by the given percentage.
* @param {string} color - The color, in hexadecimal format.
* @param {number} percent - The percentage, ranging from 0 to 100.
* @return {string} The darkened color.
*/
darken: function(color, percent) {
// ..
}
};
如果您在物件文字之外新增屬性至 module.exports，您也可以使用此模式
/**
* Color mixer.
* @module color/mixer
*/
module.exports = {
/**
* Blend two colors together.
* @param {string} color1 - The first color, in hexadecimal format.
* @param {string} color2 - The second color, in hexadecimal format.
* @return {string} The blended color.
*/
blend: function(color1, color2) {
// ...
}
};
/**
* Darken a color by the given percentage.
* @param {string} color - The color, in hexadecimal format.
* @param {number} percent - The percentage, ranging from 0 to 100.
* @return {string} The darkened color.
*/
module.exports.darken = function(color, percent) {
// ..
};
指定給 'module.exports' 的函式
如果您將函式指定給 module.exports，JSDoc 會自動設定函式的正確長名稱
/**
* Color mixer.
* @module color/mixer
*/
/**
* Blend two colors together.
* @param {string} color1 - The first color, in hexadecimal format.
* @param {string} color2 - The second color, in hexadecimal format.
* @return {string} The blended color.
*/
module.exports = function(color1, color2) {
// ...
};
相同模式適用於建構函式
/**
* Color mixer.
* @module color/mixer
*/
/** Create a color mixer. */
module.exports = function ColorMixer() {
// ...
};
指定給 'module.exports' 的字串、數字或布林值
對於指定給 module.exports 的值類型 (字串、數字和布林值)，您必須使用 @type 標籤 在與 @module 標籤相同的 JSDoc 註解中記錄匯出值的類型
/**
* Module representing the word of the day.
* @module wotd
* @type {string}
*/
module.exports = 'perniciousness';
值指定給 'module.exports' 和區域變數
如果您的模組匯出未直接指定給 module.exports 的符號，您可以使用 @exports 標籤取代 @module 標籤。@exports 標籤會告知 JSDoc 符號表示模組匯出的值。
/**
* Color mixer.
* @exports color/mixer
*/
var mixer = module.exports = {
/**
* Blend two colors together.
* @param {string} color1 - The first color, in hexadecimal format.
* @param {string} color2 - The second color, in hexadecimal format.
* @return {string} The blended color.
*/
blend: function(color1, color2) {
// ...
}
};
新增至 'this' 的屬性
當模組新增屬性至其 this 物件時，JSDoc 3 會自動辨識新屬性已由模組匯出
/**
* Module for bookshelf-related utilities.
* @module bookshelf
*/
/**
* Create a new Book.
* @class
* @param {string} title - The title of the book.
*/
this.Book = function(title) {
/** The title of the book. */
this.title = title;
}