CommonJSモジュール
概要
CommonJSモジュールCommonJSモジュールのドキュメント作成を支援するために、JSDoc 3はCommonJS仕様で使用されている多くの規約（例えば、exportsオブジェクトへのプロパティの追加）を理解しています。さらに、JSDocはCommonJS標準を拡張するNode.jsモジュールの規約（例えば、module.exportsへの値の代入）も認識します。従っているコーディング規約によっては、JSDocがコードを理解するのに役立つ追加タグをいくつか提供する必要がある場合があります。
このページでは、いくつかの異なるコーディング規約を使用するCommonJSおよびNode.jsモジュールのドキュメント作成方法について説明します。非同期モジュール定義（AMD）モジュール（「RequireJSモジュール」とも呼ばれる）のドキュメントを作成する場合は、AMDモジュールを参照してください。
モジュール識別子
ほとんどの場合、CommonJSまたはNode.jsモジュールには、@moduleタグを含むスタンドアロンのJSDocコメントを含める必要があります。@moduleタグの値は、require()関数に渡されるモジュール識別子である必要があります。例えば、ユーザーがrequire('my/shirt')を呼び出すことでモジュールを読み込む場合、JSDocコメントには@module my/shirtタグが含まれます。
値なしで@moduleタグを使用すると、JSDocはファイルパスに基づいて正しいモジュール識別子を推測しようとします。
別のJSDocコメントからモジュールを参照するためにJSDoc namepathを使用する場合は、接頭辞module:を追加する必要があります。例えば、モジュールmy/pantsのドキュメントをモジュールmy/shirtにリンクさせたい場合、@seeタグを使用して、次のようにmy/pantsを記述できます。
/**
* Pants module.
* @module my/pants
* @see module:my/shirt
*/
同様に、モジュールの各メンバーのnamepathは、module:で始まり、モジュール名が続きます。例えば、my/pantsモジュールがJeansコンストラクタをエクスポートし、Jeansがhemというインスタンスメソッドを持つ場合、インスタンスメソッドのlongnameは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はexports.washではなくローカル変数washの直前にJSDocコメントが表示されるため、washをエクスポートされたメソッドとして自動的に文書化しません。解決策の1つは、メソッドの正しいlongnameを定義する@aliasタグを追加することです。この場合、メソッドはモジュールmy/shirtの静的メンバーであるため、正しいlongnameは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は各プロパティの正しいlongnameを自動的に設定します。
/**
* 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は関数の正しいlongnameを自動的に設定します。
/**
* 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に割り当てられた値型（文字列、数値、ブール値）の場合、@moduleタグと同じJSDocコメント内で@typeタグを使用して、エクスポートされた値の型を文書化する必要があります。
/**
* Module representing the word of the day.
* @module wotd
* @type {string}
*/
module.exports = 'perniciousness';
'module.exports'とローカル変数に割り当てられた値
モジュールがmodule.exportsに直接割り当てられていないシンボルをエクスポートする場合、@moduleタグの代わりに@exportsタグを使用できます。@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;
}