JavaScript ドキュメント規約

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

何をドキュメントするか

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

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

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

Top ↑

ドキュメントのヒント

Top ↑

文体

「短い説明 (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」を使用してください。

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

Top ↑

文法

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

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

Top ↑

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

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

短い説明 (Short description):

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

長い説明 (Long description):

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

@param および @return タグ:

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

Top ↑

行の折り返し

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

Top ↑

コメントの行揃え

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

例:

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

Top ↑

関数

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

  • 要約: 関数の目的を説明する簡潔な単一の文。末尾はピリオド。
  • 説明: 要約を補足する詳細な説明。文の末尾はピリオド。
  • @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} 戻り値の説明。
 */

Top ↑

Backbone クラス

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}   attributes.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 を参照してください。

Top ↑

ローカル関数

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

/**
 * 関数の説明。関数が 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,
} );

Top ↑

ローカルの ancestor

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

Top ↑

クラスメンバー

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

  • 短い説明: 末尾にはピリオドを使用する。
  • @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
 */

Top ↑

名前空間

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

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

Top ↑

インラインコメント

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

Top ↑

単一行コメント

// Extract the array values.

Top ↑

複数行コメント

/*
 * 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つのアスタリスク) を使用してください。

Top ↑

ファイルヘッダー

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

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

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

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

Top ↑

サポートされる JSDoc タグ

タグ説明
@abstractこのメソッドは継承側から実装、またはオーバーライドできる。
@accessこのメンバーのアクセスレベルを指定する (private、public、protected)
@aliasメンバーに別名があるものとして扱う。
@augmentsこのクラスは親クラスから継承する。
@author項目の作者を識別
@borrowsこのオブジェクトは別のオブジェクトの何かを使用する。
@callbackコールバック関数をドキュメント
@classこの関数はクラスのコンストラクター
@classdescクラス全体の記述に次のテキストを使用する。
@constantオブジェクトを定数としてドキュメント
@constructsこの関数メンバーは前のクラスのコンストラクターになる。
@copyright著作権情報をドキュメント
@defaultデフォルト値をドキュメント
@deprecated非推奨の機能であることをドキュメント
@descriptionシンボルについて記述
@enum関連するプロパティのコレクションをドキュメント
@eventイベントをドキュメント
@exampleドキュメントされた項目の使用例を提示
@exportsJavaScript モジュールからエクスポートされるメンバーを識別
@external外部クラス、名前空間、モジュールをドキュメント
@fileファイルについて記述
@firesこのメソッドが発火するイベントを説明する。
@function関数、またはメソッドについて記述
@globalグローバルオブジェクトをドキュメント
@ignore[todo] 最終出力かこれらを除去
@inner内部オブジェクトをドキュメント
@instanceインスタンスメンバーをドキュメント
@kindこのシンボルの種類は何か?
@lends与えられた名前でシンボルに属すようにオブジェクトリテラルのプロパティをドキュメント
@license[todo] このコードに適用されるソフトウエアライセンスをドキュメント
@linkインラインタグ – リンクを作成
@memberメンバーをドキュメント
@memberofこのシンボルは親のシンボルに属す。
@mixesこのオブジェクトは他のオブジェクトのすべてのメンバーを mixin する。
@mixinmixin オブジェクトをドキュメント
@moduleJavaScript モジュールをドキュメント
@nameオブジェクトの名前をドキュメント
@namespace名前空間オブジェクトをドキュメント
@param関数へのパラメータをドキュメント
@privateこのシンボルは private
@propertyオブジェクトのプラパティをドキュメント
@protectedメンバーは protected
@publicこのシンボルは public
@readonlyこのシンボルはリードオンリー
@requiresこのファイルは JavaScript モジュールが必要
@returns関数の戻り値をドキュメント
@see詳細については他のドキュメントを参照
@sinceいつ、この機能は追加されたか?
@staticstatic メンバーをドキュメント
@this‘this’ キーワードはここで何を参照するか?
@throwsどんなエラーがスローされるかを記述
@todo完了すべきタスクをドキュメント
@tutorial同梱されるチュートリアルファイルへのリンクを挿入
@typeオブジェクトの型をドキュメント
@typedefカスタムタイプをドキュメント
@variation同一名で異なるオブジェクトを区別
@versionアイテムのバージョン番号をドキュメント

Top ↑

サポートされない JSDoc タグ

タグなぜサポートされないか
@summary使わない。完全な説明 (full description) から要約 (summary) を分離する方法については例を参照。
@virtualサポートされないシノニム。代わりに @abstract を使用。
@extendsサポートされないシノニム。代わりに @augments を使用。
@constructorサポートされないシノニム。代わりに @class を使用。
@constサポートされないシノニム。代わりに @constant を使用。
@defaultvalueサポートされないシノニム。代わりに @default を使用。
@descサポートされないシノニム。代わりに @description を使用。
@hostサポートされないシノニム。代わりに @external を使用。
@fileoverviewサポートされないシノニム。代わりに @file を使用。
@overviewサポートされないシノニム。代わりに @file を使用。
@emitsサポートされないシノニム。代わりに @fires を使用。
@funcサポートされないシノニム。代わりに @function を使用。
@methodサポートされないシノニム。代わりに @function を使用。
@varサポートされないシノニム。代わりに @member を使用。
@emitsサポートされないシノニム。代わりに @fires を使用。
@argサポートされないシノニム。代わりに @param を使用。
@argumentサポートされないシノニム。代わりに @param を使用。
@propサポートされないシノニム。代わりに @property を使用。
@returnサポートされないシノニム。代わりに @returns を使用。
@exceptionサポートされないシノニム。代わりに @throws を使用。

原文

最終更新日: