JavaScript ドキュメント規約

WordPress は、インラインの JavaScript ドキュメント規約として「JSDoc 3 Standard」に遵守します。

WordPress での JavaScript ドキュメント形式は、フォーマットされたドキュメントブロックかインラインコメントになります。

以下のリストは WordPress JavaScript ファイル内でドキュメントする項目の例です。

• 関数、およびクラスのメソッド
• オブジェクト
• クロージャ
• オブジェクトプロパティ
• require
• イベント
• ファイルヘッダー

「短い説明 (short description)」を書く場合には、明確でシンプルな、短い文を心がけてください。「いつ」「何を」実行するのかをドキュメントしてください。「なぜ」を含める必要性はほとんどないはずです。 どうしても「なぜ」が必要であれば「長い説明 (long description)」に記述してください。

関数やクロージャは「三人称単数」の要素です。説明を記述する場合も「三人称単数の動詞」を使用してください。

ヒント: 三人称単数の動詞の活用に悩む場合は、関数、フック、クラス、メソッドの説明を書く場合、先頭に「It」をつけて考えてください。

• 正: “(It) Does something.”
• 誤: “(It) Do something.”

関数: この関数は「何を」するのか?

• 正: Handles a click on X element. (要素「X」のクリックを処理する)
• 誤: Included for back-compat for X element. (要素「X」の後方互換性のために追加された)

@since: WordPress に追加されたバージョン番号等を調べる場合は、ツール「svn blame」の使用を推奨します。

ツールを使用してもバージョン番号を特定できない場合は、「@since Unknown」を使用してください。

コードリファクタリング: ドキュメントを編集する際に、ファイル内のコードはリファクタリングしないでください。

説明文の要素は完全な文として記述してください。例外はファイルヘッダーの 要約 (summary) です。この要約は文章ではなく「タイトル」を意図しているためです。

要約、説明 (description)、Parameter や Return の説明内で要素を並べる際には serial comma (Oxford comma) を使用してください。(例: A, B and C)

次のガイドラインに従うことで DocBlock の内容が、コードリファレンス用に正しくパースされます。

短い説明 (Short description):

「短い説明」は単一の文で書き、マークアップしないでください。説明が HTML 要素やタグを参照する場合は、「<a>」ではなく、「link タグ」のように記述してください。例: “Fires when printing the link tag in the header”。

長い説明 (Long description):

「長い説明」では、必要であればマークダウンを使用できます。

@param および @return タグ:

これらのタグの説明では HTML もマークダウンも許されません。HTML 要素やタグは「audio 要素」や「link タグ」のように記述してください。

DocBlock のテキストは80文字分で次の行に折り返してください。例えば DocBlock が20文字分インデントしている場合には、100文字目の位置で折り返します。ただし120文字目以上は超えないでください。

関連するコメントは、スペースを使用して位置を揃え、可読性を上げてください。

例:

/**
 * @param {very_long_type} name           説明。
 * @param {type}           very_long_name 説明。
 */

関数は次のようにフォーマットしてください。

• 要約: 関数の目的を説明する簡潔な単一の文。末尾はピリオド。
• 説明: 要約を補足する詳細な説明。文の末尾はピリオド。
• @deprecated x.x.x: 非推奨になった関数のみに使用する。どの WordPress バージョンで非推奨になったかを示す常に3組の数字 (例 @deprecated 3.6.0) と代替の関数。
• @since x.x.x: 最初に導入されたバージョンを表す3組の数字 (例: @since 3.6.0)。大きな変更が合った場合は、履歴の目的で、追加の @since タグ、バージョン、説明を追加する。
• @access: 関数が private の場合のみ使用。関数が private なら、内部使用専用であり、コードリファレンスにドキュメントされない。
• @class: クラスのコンストラクタに使用
• @augments: クラスのコンストラクタで、クラスの直接の親をリストする。
• @mixes: オブジェクトにミックスされる mixin をリストする。
• @alias: 最初にこの関数が一時変数に割り当てられた場合、名前を変更することができる。
• @memberof: JSDoc が自動的に解決できない場合、この関数が含まれる名前空間
• @static: クラスに対し、クラスコンストラクタで関数が static メソッドであることを示す。
• @see: 依存する関数やクラス
• @link: 詳細情報への URL
• @fires: 関数から発火されるイベント。特定のクラスに紐付けられたイベントはクラス名をリストしなければならない。
• @listens: この関数が期待するイベント。イベントはイベント名前空間の接頭辞を付ける必要がある。特定のクラスに紐付けられたイベントはクラス名をリストしなければならない。
• @global: この関数をグローバル名前空間に含まれるグローバル関数としてマークする。
• @param: 変数の簡単な説明。JSDoc @param 構文を使用して、例えば、変数がオプションなら、そのデフォルト値などの事項を記述する。最後はピリオド。
• @yield: ジェネレータ関数 に関して、この関数から yield されると期待する値の説明。他の説明同様、最後はピリオドで終える。
• @return: 注意: 説明の末尾はピリオド

/**
 * 要約 (末尾はピリオド)
 *
 * 説明 (末尾はピリオド)
 *
 * @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
 * @link URL
 * @global
 *
 * @fires   eventName
 * @fires   className#eventName
 * @listens event:eventName
 * @listens className~event:eventName
 *
 * @param {type}   var           説明。
 * @param {type}   [var]         オプション値の説明。
 * @param {type}   [var=default] デフォルト値のあるオプション変数の説明。
 * @param {Object} objectVar     説明。
 * @param {type}   objectVar.key objectVar パラメータ内のキーの説明。
 *
 * @yield {type} yield 値の説明。
 *
 * @return {type} 戻り値の説明。
 */

Backbone の extend 呼び出しは次のようにフォーマットしてください。

• @lends このタグは JSDoc に Backbone からの extend 関数をクラス定義として認識させます。クラス定義を含む Object の直前に置いてください。

Backbone の initialize 関数は次のようにフォーマットしてください。

• 要約: 関数の目的を説明する簡潔な単一の文。末尾はピリオド。
• 説明: 要約を補足する詳細な説明。文の末尾はピリオド。
• @deprecated x.x.x: 非推奨になったクラスのみに使用する。どの WordPress バージョンで非推奨になったかを示す常に3組の数字 (例 @deprecated 3.6.0) と代替のクラス。
• @since x.x.x: 最初に導入されたバージョンを表す3組の数字 (例: @since 3.6.0)。大きな変更が合った場合は、履歴の目的で、追加の @since タグ、バージョン、説明を追加する。
• @constructs: この関数をクラスのコンストラクタとしてマークする。
• @augments: 直接の親をリストする。
• @mixes: クラスにミックスされる mixin をリストする。
• @requires: このクラスが必要とするモジュールをリストする。複数の @requires タグを使用可能。
• @alias: 最初にこのクラスが一時変数に割り当てられた場合、名前を変更することができる。
• @memberof: JSDoc が自動的に解決できない場合、このクラスが含まれる名前空間
• @static: クラスに対し、クラスコンストラクタで関数が static メソッドであることを示す。
• @see: 依存する関数やクラス
• @link: 詳細情報への URL
• @fires: コンストラクターから発火されるイベント。クラス名をリストする。
• @param: initializeに明示的にリストしていないものも含め、コンストラクターに渡す引数をドキュメントする。最後はピリオド。
  • Backbone Models は attributes と options パラメータに渡される。
  • Backbone Views は options パラメータに渡される。

Class = Parent.extend( /** @lends namespace.Class.prototype */{
	/**
	 * 要約 (末尾はピリオド)
	 *
	 * 説明 (末尾はピリオド)
	 *
	 * @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
	 * @link  URL
	 * @fires Class#eventName
	 *
	 * @param {Object} attributes     モデルの属性。
	 * @param {type}   attributes.key モデルの属性の1つ。
	 * @param {Object} [options]      モデルのオプション。
	 * @param {type}   options.key モデルのオプションの1つ。
	 */initialize: function() {
		// 何かを実行する。
	}
} );

Backbone クラスに initialize 関数がない場合、次のように @inheritDoc を使用してドキュメントしてください。

/**
 * 要約 (末尾はピリオド)
 *
 * 説明 (末尾はピリオド)
 *
 * @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
 * @link  URL
 */
Class = Parent.extend( /** @lends namespace.Class.prototype */{
// 関数とプロパティ。
} );

注意: 現在、JSDoc の inheritDoc タグのバグのため、期待どおりに機能しません。こちらの issue を参照してください。

関数がクラスメンバーとして割り当てられる前に、ローカル変数に割り当てられる場合があります。 このような関数は、~ を使用して名前空間の内部関数としてマークしてください。 次のようにフォーマットします。

/**
 * 関数の説明。関数が private である限り、ここで任意の JSDoc を使用可能
 *
 * @alias namespace~doStuff
 */var doStuff = function () {
// 何かを実行する。
};

Class = Parent.extend( /** @lends namespace.Class.prototype */{
	/**
	 * クラス定義
	 *
	 * @constructs namespace.Class
	 *
	 * @borrows namespace~doStuff as prototype.doStuff
	 */initialize: function() {
	// 何かを実行する。
	},

	/*
	 * この関数は自動的に、上からコピーされたドキュメントを持つ。
	 * コメントで @borrows を使用して関数を説明していることを注記しなければならない。
	 * このとき DocBlock の /** ではなく、/* または // を使用すること。
	 */doStuff: doStuff,
} );

クラスは、ローカル変数にしか割り当てられない ancestor (先祖) を持つ場合があります。このようなクラスは、その子クラスの名前空間に割り当て、~ を使用して内部クラスにする必要があります。

クラスメンバーは次のようにフォーマットしてください。

• 短い説明: 末尾にはピリオドを使用する。
• @since x.x.x: 常に3組の数字 (例: @since 3.6.0)
• @access: メンバーが private、protected、public のどれかを示す。private メンバーは内部のみでの使用を想定する。
• @type: クラスメンバーのタイプをリストする。
• @property: Object の場合、このオブジェクトが持つすべてのプロパティをリストする。最後にピリオドを使用する。
• @member: オプションとして、 JSDoc のメンバー検知を上書きする。@type の代わりにクラスメンバーに強制する。
• @memberof: オプションとして、どのクラスのメンバーかを上書きする。

/**
 * 短い説明 (末尾はピリオド)
 *
 * @since  x.x.x
 * @access (private、protected、または public)
 *
 * @type     {type}
 * @property {type} key 説明。
 *
 * @member   {type} realName
 * @memberof className
 */

名前空間は次のようにフォーマットしてください。

• 短い説明: 最後にピリオドを使用する。
• @namespace: このシンボルを名前空間としてマークする。オプションとして上書きする名前を提供する。
• @since x.x.x: 常に3組の数字 (例: @since 3.6.0)
• @memberof: この名前空間が含まれる名前空間。
• @property: この名前空間が expose するプロパティ。最後にピリオドを使用する。

/**
 * 短い説明 (末尾はピリオド)
 *
 * @namespace realName
 * @memberof  parentNamespace
 *
 * @since x.x.x
 *
 * @property {type} key 説明。
 */

メソッドや関数のインラインコメントは次のようにフォーマットしてください。

// 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.
 */

重要な注意: 複数行のコメントを /** (2つのアスタリスク) で始めないでください。代わりに /* (1つのアスタリスク) を使用してください。

JSDoc ファイルヘッダーブロックにはファイルに含まれる内容の概要を書きます。

可能であれば常にすべての WordPress JavaScript ファイルにヘッダーブロックを記述してください。

WordPress は JSHint を使用して全般的なコードの品質を検証します。インライン構成オプションはヘッダーブロックの最後に記述してください。

/**
 * 要約 (末尾はピリオド)
 *
 * 説明 (末尾はピリオド)
 *
 * @link   URL
 * @file   This files defines the MyClass class.
 * @author AuthorName.
 * @since  x.x.x
 *//** jshint {ここにインライン構成} */

原文

最終更新日: 2022年8月16日