構文

@variation <variationNumber>

概要

場合によっては、コードに同じ長ったらしい名前を持つ複数のシンボルが含まれることがあります。たとえば、グローバルクラスと `Widget` という名前のトップレベルのネームスペースの両方がある場合があります。そのような場合、"{@link Widget}" または "@memberof Widget" とは何を意味しますか？グローバルネームスペースか、グローバルクラスですか？

バリエーションは、同じ長ったらしい名前を持つ異なるシンボルを JSDoc で区別するために役立ちます。たとえば、Widget クラスの JSDoc コメントに "@variation 2" が追加されている場合、"{@link Widget(2)}" はクラスを参照し、"{@link Widget}" はネームスペースを参照します。または、@alias や @name などのタグでシンボルの指定にバリエーションを組み込むことができます（たとえば、"@alias Widget(2)"）。

@variation タグには任意の値を指定できます。値と長ったらしい名前の組み合わせが長ったらしい名前のグローバルに一意なバージョンになる限りです。ベストプラクティスとして、値の選択に予測可能なパターンを使用すると、コードのドキュメント化が容易になります。

例

次の例では、@variation タグを使用して、Widget クラスと Widget ネームスペースを区別します。

/**
 * The Widget namespace.
 * @namespace Widget
 */

// you can also use '@class Widget(2)' and omit the @variation tag
/**
 * The Widget class. Defaults to the properties in {@link Widget.properties}.
 * @class
 * @variation 2
 * @param {Object} props - Name-value pairs to add to the widget.
 */
function Widget(props) {}

/**
 * Properties added by default to a new {@link Widget(2)} instance.
 */
Widget.properties = {
    /**
     * Indicates whether the widget is shiny.
     */
    shiny: true,
    /**
     * Indicates whether the widget is metallic.
     */
    metallic: true
};

関連リンク

• @alias
• @name