AMD モジュール
概要
JSDoc 3 では、非同期モジュール定義 (AMD) API を使用するモジュールをドキュメント化できます。この API は、RequireJS などのライブラリで実装されています。このページでは、モジュールで使用しているコーディング規則に基づき、JSDoc 用の AMD モジュールをドキュメント化する方法を説明します。
CommonJS モジュールまたは Node.js モジュールのドキュメント化については、CommonJS モジュール で説明を参照してください。
モジュール ID
AMD モジュールをドキュメント化するときに、require() 関数に渡される識別子をドキュメント化するために、@exports タグ または @module タグ を使用します。たとえば、ユーザーが require('my/shirt', /* callback */) を呼び出してモジュールをロードする場合、タグ @exports my/shirt または @module my/shirt を含む JSDoc コメントを作成します。以下の例は、これらのどちらのタグを使用するかを判断する際に役立ちます。
値なしで @exports タグまたは @module タグを使用すると、JSDoc はファイルパスに基づいて正しいモジュール ID を推測しようとします。
別の 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 です。
オブジェクトリテラルを返す関数
AMD モジュールをオブジェクトリテラルを返す関数として定義する場合、@exports タグ を使用してモジュールの名前をドキュメント化します。JSDoc は、オブジェクトのプロパティがモジュールのメンバーであることを自動的に検出します。
define('my/shirt', function() {
/**
* A module representing a shirt.
* @exports my/shirt
*/
var shirt = {
/** The module's `color` property. */
color: 'black',
/**
* Create a new Turtleneck.
* @class
* @param {string} size - The size (`XS`, `S`, `M`, `L`, `XL`, or `XXL`).
*/
Turtleneck: function(size) {
/** The class's `size` property. */
this.size = size;
}
};
return shirt;
});
別の関数を返す関数
モジュールをコンストラクターなどの別の関数がエクスポートする関数として定義する場合、@module タグ を使用したスタンドアロンコメントを使用してモジュールをドキュメント化できます。その後、@alias タグ を使用して、関数がモジュールと同じロングネームを使用することを JSDoc に伝えることができます。
/**
* A module representing a jacket.
* @module my/jacket
*/
define('my/jacket', function() {
/**
* Create a new jacket.
* @class
* @alias module:my/jacket
*/
var Jacket = function() {
// ...
};
/** Zip up the jacket. */
Jacket.prototype.zip = function() {
// ...
};
return Jacket;
});
戻り値のステートメントで宣言されたモジュール
関数の return ステートメントにモジュールオブジェクトを宣言する場合、@module タグ を使用したスタンドアロンコメントを使用してモジュールをドキュメント化できます。その後、@alias タグ を追加して、モジュールオブジェクトがモジュールと同じロングネームを持つことを JSDoc に伝えることができます。
/**
* Module representing a shirt.
* @module my/shirt
*/
define('my/shirt', function() {
// Do setup work here.
return /** @alias module:my/shirt */ {
/** Color. */
color: 'black',
/** Size. */
size: 'unisize'
};
});
関数に渡されるモジュールオブジェクト
モジュールオブジェクトがモジュールを定義する関数に渡される場合、関数パラメータに @exports タグ を追加してモジュールをドキュメント化できます。このパターンは JSDoc 3.3.0 以降でサポートされています。
define('my/jacket', function(
/**
* Utility functions for jackets.
* @exports my/jacket
*/
module) {
/**
* Zip up a jacket.
* @param {Jacket} jacket - The jacket to zip up.
*/
module.zip = function(jacket) {
// ...
};
});
1 つのファイルに定義された複数のモジュール
1 つの JavaScript ファイルに複数の AMD モジュールを定義する場合、@exports タグ を使用して各モジュールオブジェクトをドキュメント化します。
// one module
define('html/utils', function() {
/**
* Utility functions to ease working with DOM elements.
* @exports html/utils
*/
var utils = {
/**
* Get the value of a property on an element.
* @param {HTMLElement} element - The element.
* @param {string} propertyName - The name of the property.
* @return {*} The value of the property.
*/
getStyleProperty: function(element, propertyName) { }
};
/**
* Determine if an element is in the document head.
* @param {HTMLElement} element - The element.
* @return {boolean} Set to `true` if the element is in the document head,
* `false` otherwise.
*/
utils.isInHead = function(element) { }
return utils;
}
);
// another module
define('tag', function() {
/** @exports tag */
var tag = {
/**
* Create a new Tag.
* @class
* @param {string} tagName - The name of the tag.
*/
Tag: function(tagName) {
// ...
}
};
return tag;
});