JavaScriptドキュメンテーションスタンダード（JavaScript Documentation Standards）

文書化すべき内容

WordPressにおけるJavaScriptの文書化は、フォーマットされた文書ブロックまたはインラインコメントの形を取ります。

以下は、WordPressのJavaScriptファイルで文書化すべき内容のリストです:

• 関数とクラスメソッド
• オブジェクト
• クロージャ
• オブジェクトプロパティ
• 要件
• イベント
• ファイルヘッダー
  

文書化のヒント

言語

短い説明は明確でシンプル、かつ簡潔であるべきです。「何」と「いつ」を文書化し、「なぜ」はほとんど含める必要はありません。「なぜ」は必要に応じて長い説明に含めることができます。例えば:

関数とクロージャは三人称単数の要素であり、各々が何をするかを説明するために三人称単数動詞を使用する必要があります。

三人称単数動詞の活用を思い出すのに助けが必要ですか？関数、フック、クラス、またはメソッドの要約の前に「それ」を付けることを想像してください:

• 良い: 「(それ) は何かをします。」
• 悪い: 「(それ) は何かをする。」

関数: 関数は何をしますか？

• 良い: X要素のクリックを処理します。
• 悪い: X要素のための後方互換性のために含まれています。

@since: WordPressに何かが追加されたバージョンを検索する際に推奨されるツールは svn blame です。

これらのツールを使用した後にバージョン番号が特定できない場合は、@since Unknownを使用してください。

コードリファクタリング: 文書の変更時にファイル内のコードをリファクタリングしないでください。

文法

記述要素は完全な文として書かれるべきです。この基準の唯一の例外は、ファイルヘッダーの要約であり、これは文よりもファイルの「タイトル」として意図されています。

要約、説明、パラメータまたは戻り値の説明で要素を列挙する際には、連続（オックスフォード）カンマを使用するべきです。

フォーマットガイドライン

以下のガイドラインに従って、ドキュメントブロックの内容がコードリファレンスに含まれるために適切に解析できるようにします。

短い説明:

短い説明は1文であり、いかなるマークアップも含まれてはいけません。説明がHTML要素またはタグを指す場合は、「リンクタグ」と書くべきであり、「<a>」とは書かないでください。例えば: 「ヘッダーでリンクタグを印刷するときに発火します」。

長い説明:

必要に応じて、長い説明ではMarkdownを使用できます。

@paramおよび@returnタグ:

これらのタグの説明にはHTMLまたはMarkdownは許可されていません。HTML要素とタグは「オーディオ要素」または「リンクタグ」として書かれるべきです。

行の折り返し

DocBlockテキストは、80文字のテキストの後に次の行に折り返すべきです。DocBlock自体が左に20文字分インデントされている場合、折り返しは位置100で発生する可能性がありますが、合計120文字を超えてはなりません。

コメントの整列

関連するコメントは、より読みやすくするために整列されるように間隔を空けるべきです。

例えば:

/**
 * @param {very_long_type} name           Description.
 * @param {type}           very_long_name Description.
 */

関数

関数は以下のようにフォーマットされるべきです:

• 要約: 関数の目的についての簡潔な1行の説明。文末にピリオドを使用します。
• 説明: 要約の補足として、より詳細な説明を提供します。文末にピリオドを使用します。
• @deprecated x.x.x: 非推奨の関数にのみ使用し、関数が非推奨になったバージョンを提供します。これは常に3桁であるべきです（例: @deprecated 3.6.0）、および代わりに使用する関数を提供します。
• @since x.x.x: 初回導入のために3桁であるべきです（例: @since 3.6.0）。重要な変更が行われた場合は、追加の@sinceタグ、バージョン、および説明を追加して変更履歴として機能させるべきです。
• @access: プライベートな場合にのみ関数に使用します。関数がプライベートである場合、それは内部使用のみを意図しており、コードリファレンスには文書化されません。
• @class: クラスのコンストラクタに使用します。
• @augments: クラスのコンストラクタの場合、直接の親をリストします。
• @mixes: オブジェクトにミックスインされたミックスインをリストします。
• @alias: この関数が一時変数に最初に割り当てられた場合、文書化される名前を変更できます。
• @memberof: JSDocが自動的に解決できない場合、この関数が含まれる名前空間を示します。
• @static: クラスのために、関数がクラスコンストラクタの静的メソッドであることを示します。
• @see: 依存している関数またはクラス。
• @link: さらなる情報を提供するURL。
• @fires: 関数によって発火されるイベント。特定のクラスに関連付けられたイベントは、クラス名をリストするべきです。
• @listens: この関数がリッスンするイベント。イベントはイベント名前空間でプレフィックスされる必要があります。特定のクラスに関連付けられたイベントは、クラス名をリストするべきです。
• @global: この関数をグローバル関数としてマークし、グローバル名前空間に含めることを示します。
• @param: 変数の簡潔な説明を提供し、特に（例: 変数がオプションである場合、そのデフォルト）をJSDoc @param構文で示します。文末にピリオドを使用します。
• @yield: ジェネレーター関数の場合、この関数から期待される値の説明。その他の説明と同様に、文末にピリオドを含めます。
• @return: 説明の後にピリオドを記載します。

/**
 * Summary. (use period)
 *
 * Description. (use period)
 *
 * @since      x.x.x
 * @deprecated x.x.x Use new_function_name() instead.
 * @access     private
 *
 * @class
 * @augments parent
 * @mixes    mixin
 *
 * @alias    realName
 * @memberof namespace
 *
 * @see  Function/class relied on
 * @link URL
 * @global
 *
 * @fires   eventName
 * @fires   className#eventName
 * @listens event:eventName
 * @listens className~event:eventName
 *
 * @param {type}   var           Description.
 * @param {type}   [var]         Description of optional variable.
 * @param {type}   [var=default] Description of optional variable with default variable.
 * @param {Object} objectVar     Description.
 * @param {type}   objectVar.key Description of a key in the objectVar parameter.
 *
 * @yield {type} Yielded value description.
 *
 * @return {type} Return value description.
 */

Backboneクラス

Backboneのextend呼び出しは以下のようにフォーマットされるべきです:

• @lends このタグは、JSDocがBackboneのextend関数をクラス定義として認識できるようにします。これは、クラス定義を含むオブジェクトの直前に配置するべきです。

Backboneのinitialize関数は以下のようにフォーマットされるべきです:

• 要約: 関数の目的についての簡潔な1行の説明。文末にピリオドを使用します。
• 説明: 要約の補足として、より詳細な説明を提供します。文末にピリオドを使用します。
• @deprecated x.x.x: 非推奨のクラスにのみ使用し、クラスが非推奨になったバージョンを提供します。これは常に3桁であるべきです（例: @deprecated 3.6.0）、および代わりに使用するクラスを提供します。
• @since x.x.x: 初回導入のために3桁であるべきです（例: @since 3.6.0）。重要な変更が行われた場合は、追加の@sinceタグ、バージョン、および説明を追加して変更履歴として機能させるべきです。
• @constructs: この関数をこのクラスのコンストラクタとしてマークします。
• @augments: 直接の親をリストします。
• @mixes: クラスにミックスインされたミックスインをリストします。
• @requires: このクラスが必要とするモジュールをリストします。複数の@requiresタグを使用できます。
• @alias: このクラスが一時変数に最初に割り当てられた場合、文書化される名前を変更できます。
• @memberof: JSDocが自動的に解決できない場合、このクラスが含まれる名前空間を示します。
• @static: クラスのために、関数がクラスコンストラクタの静的メソッドであることを示します。
• @see: 依存している関数またはクラス。
• @link: さらなる情報を提供するURL。
• @fires: コンストラクタによって発火されるイベント。クラス名をリストするべきです。
• @param: コンストラクタに渡される引数を文書化します。initializeに明示的にリストされていなくても、文書化します。文末にピリオドを使用します。
  • Backboneモデルにはattributesおよびoptionsパラメータが渡されます。
  • Backboneビューにはoptionsパラメータが渡されます。

Class = Parent.extend( /** @lends namespace.Class.prototype */{
   /**
     * Summary. (use period)
   *
     * Description. (use period)
   *
     * @since      x.x.x
     * @deprecated x.x.x Use new_function_name() instead.
     * @access     private
   *
     * @constructs namespace.Class
     * @augments   Parent
     * @mixes      mixin
   *
     * @alias    realName
     * @memberof namespace
   *
     * @see   Function/class relied on
     * @link  URL
     * @fires Class#eventName
   *
     * @param {Object} attributes     The model's attributes.
     * @param {type}   attributes.key One of the model's attributes.
     * @param {Object} [options]      The model's options.
     * @param {type}   options.key One of the model's options.
   */
   initialize: function() {
   //Do stuff.
   }
} );

Backboneクラスに初期化関数がない場合は、@inheritDocを使用して文書化するべきです:

/**
 * Summary. (use period)
 *
 * Description. (use period)
 *
 * @since      x.x.x
 * @deprecated x.x.x Use new_function_name() instead.
 * @access     private
 *
 * @constructs namespace.Class
 * @memberOf   namespace
 * @augments   Parent
 * @mixes      mixin
 * @inheritDoc
 *
 * @alias    realName
 * @memberof namespace
 *
 * @see   Function/class relied on
 * @link  URL
 */
Class = Parent.extend( /** @lends namespace.Class.prototype */{
// Functions and properties.
} );

注意: 現在、JSDocのinheritDocタグのバグのため、期待される機能を提供していません。詳細は JSDocs3 issue 1012 を参照してください。

ローカル関数

時には、関数がクラスメンバーとして割り当てられる前にローカル変数に割り当てられることがあります。

そのような関数は、それを使用する名前空間の内部関数として~を使用してマークするべきです。

関数は以下のようにフォーマットされるべきです:

/**
 * Function description, you can use any JSDoc here as long as the function remains private.
 *
 * @alias namespace~doStuff
 */
var doStuff = function () {
// Do stuff.
};
Class = Parent.extend( /** @lends namespace.Class.prototype */{
   /**
     * Class description
   *
     * @constructs namespace.Class
   *
     * @borrows namespace~doStuff as prototype.doStuff
   */
   initialize: function() {
   //Do stuff.
   },
   /*
     * This function will automatically have it's documentation copied from above.
     * You should make a comment ( not a DocBlock using /**, instead use /* or // )
     * noting that you're describing this function using @borrows.
   */
   doStuff: doStuff,
} );

ローカル先祖

時には、クラスがローカル変数にのみ割り当てられた先祖を持つことがあります。そのようなクラスは、子供が属する名前空間に割り当てられ、~を使用して内部クラスにするべきです。

クラスメンバー

クラスメンバーは以下のようにフォーマットされるべきです:

• 短い説明: 文末にピリオドを使用します。
• @since x.x.x: 初回導入のために3桁であるべきです（例: @since 3.6.0）。重要な変更が行われた場合は、追加の@sinceタグ、バージョン、および説明を追加して変更履歴として機能させるべきです。
• @access: メンバーがプライベート、保護、または公開であるかどうか。プライベートメンバーは内部使用のみを意図しています。
• @type: クラスメンバーの型をリストします。
• @property: このオブジェクトが持つすべてのプロパティをリストします。オブジェクトの場合、文末にピリオドを使用します。
• @member: 必要に応じて、@typeの代わりにJSDocのメンバー検出をオーバーライドするために使用します。
• @memberof: 必要に応じて、これはどのクラスのメンバーであるかをオーバーライドするために使用します。

/**
 * Short description. (use period)
 *
 * @since  x.x.x
 * @access (private, protected, or public)
 *
 * @type     {type}
 * @property {type} key Description.
 *
 * @member   {type} realName
 * @memberof className
 */

名前空間

名前空間は以下のようにフォーマットされるべきです:

• 短い説明: 文末にピリオドを使用します。
• @namespace: このシンボルを名前空間としてマークし、オーバーライドとして名前を提供することができます。
• @since x.x.x: 初回導入のために3桁であるべきです（例: @since 3.6.0）。重要な変更が行われた場合は、追加の@sinceタグ、バージョン、および説明を追加して変更履歴として機能させるべきです。
• @memberof: この名前空間が含まれている名前空間。
• @property: この名前空間が公開するプロパティ。文末にピリオドを使用します。

/**
 * Short description. (use period)
 *
 * @namespace realName
 * @memberof  parentNamespace
 *
 * @since x.x.x
 *
 * @property {type} key Description.
 */

インラインコメント

メソッドや関数内のインラインコメントは以下のようにフォーマットされるべきです:

単一行コメント

// Extract the array values.

複数行コメント

/*
 * This is a comment that is long enough to warrant being stretched over
 * the span of multiple lines. You'll notice this follows basically
 * the same format as the JSDoc wrapping and comment block style.
 */

重要な注意: 複数行コメントは/**（二重アスタリスク）で始めてはいけません。代わりに/*（単一アスタリスク）を使用してください。

ファイルヘッダー

JSDocファイルヘッダーブロックは、ファイルに含まれる内容の概要を提供するために使用されます。

可能な限り、すべてのWordPress JavaScriptファイルにはヘッダーブロックを含めるべきです。

WordPressは一般的なコード品質テストのためにJSHintを使用します。インライン設定オプションは、ヘッダーブロックの最後に配置するべきです。

/**
 * Summary. (use period)
 *
 * Description. (use period)
 *
 * @link   URL
 * @file   This files defines the MyClass class.
 * @author AuthorName.
 * @since  x.x.x
 */
/** jshint {inline configuration here} */

サポートされているJSDocタグ

サポートされていないJSDocタグ