JavaScript インラインドキュメント規約

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

何をドキュメントするか 何をドキュメントするか

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

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

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

Top ↑

ドキュメントのヒント ドキュメントのヒント

文体 文体

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

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

ヒント: 三人称単数の動詞の活用に悩む場合は、関数やクロージャの説明を書く場合、先頭に「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 です。この Summary は文章ではなく「タイトル」を意図しているためです。

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

Top ↑

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

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

短い説明:

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

長い説明:

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

@param および @return タグ:

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

Top ↑

行の折り返し 行の折り返し

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

コメントの行揃え

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

例:

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

Top ↑

関数 関数

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

  • Summary: 関数の目的を説明する簡潔な単一の文。最大でも2行。最後はピリオド。
  • Description: Summary を補足する詳細な説明。文の最後はピリオド。
  • @deprecated x.x.x: 非推奨になった関数のみに使用する。どの WordPress バージョンで非推奨になったかを示す常に3組の数字 (例 @deprecated 3.6.0) と代替の関数。
  • @since x.x.x: 常に3組の数字 (例: @since 3.6.0)
  • @access: 関数が private の場合のみ使用。内部使用専用となり、コードリファレンスにドキュメントされない。
  • @class: クラスのコンストラクタに使用
  • @augments: クラスのコンストラクタで、クラスの継承チェーンを直近の親クラスから先祖へリストする。
  • @mixes: オブジェクトにミックスされる mixin をリストする。
  • @alias: 最初にこの関数が一時変数に割り当てられた場合、名前を変更することができる。
  • @memberof: JSDoc が自動的に解決できない場合、この関数が含まれる名前空間
  • @static: クラスに対し、クラスコンストラクタで関数が static メソッドであることを示す。
  • @see: 依存する関数やクラス
  • @link: 詳細情報への URL
  • @fires: 関数から発火されるイベント。特定のクラスに紐付けられたイベントはクラス名をリストすべき。
  • @listens: この関数が期待するイベント。イベントはイベント名前空間の接頭辞を付ける必要がある。特定のクラスに紐付けられたイベントはクラス名をリストすべきである。
  • @global: この関数をグローバル名前空間に含まれるグローバル関数としてマークする。
  • @param: 変数の簡単な説明。JSDoc @param 構文を使用して、変数がオプションかどうかや、デフォルト値等を示す。最後はピリオド。
  • @yield: ジェネレータ関数から yield されると期待する値の説明。他の説明同様、最後はピリオドで終える。
  • @return: 注意: 説明の最後はピリオド
/**
* Summary. (ピリオドを使用する)
*
* Description. (ピリオドを使用する)
*
* @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 関数をクラス定義として認識させます。クラス定義を含む Object の直前に置いてください。

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

  • Summary: 関数の目的を説明する簡潔な単一の文。最大でも2行。最後はピリオド。
  • Description: Summary を補足する詳細な説明。文の最後はピリオド。
  • @deprecated x.x.x: 非推奨になったクラスのみに使用する。どの WordPress バージョンで非推奨になったかを示す常に3組の数字 (例 @deprecated 3.6.0) と代替のクラス。
  • @since x.x.x: 常に3組の数字 (例: @since 3.6.0)
  • @constructs: この関数をクラスのコンストラクタとしてマークする。@augments: 直接の親をリストする。
  • @mixes: クラスにミックスされる mixin をリストする。
  • @requires: このクラスが必要とするモジュールをリストする。複数の @requires タグを使用可能。
  • @alias: 最初にこのクラスが一時変数に割り当てられた場合、名前を変更することができる。
  • @memberof: JSDoc が自動的に解決できない場合、このクラスが含まれる名前空間
  • @static: クラスに対し、クラスコンストラクタで関数が static メソッドであることを示す。
  • @see: 依存する関数やクラス
  • @link: 詳細情報への URL
  • @fires: コンストラクターから発火されるイベント。クラス名をリストする。
  • @param: initializeに明示的にリストしていないものも含め、コンストラクターに渡す引数をドキュメントする。最後はピリオド。
    • Backbone Models は attributesoptions パラメータに渡される。
    • Backbone Views は options パラメータに渡される。
Class = Parent.extend( /** @lends namespace.Class.prototype */{
    /**
     * Summary. (ピリオドを使用する)
     *
     * Description. (ピリオドを使用する)
     *
     * @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}   attributes.key One of the model's options.
     */
    initialize: function() {
        // 何かする。
    }
} );

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

/**
 * Summary. (ピリオドを使用する)
 *
 * Description. (ピリオドを使用する)
 *
 * @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 */{
 // 関数とプロパティ
} );

注意: 現在、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

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

クラスメンバー

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

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

名前空間

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

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

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

/**
* Summary. (ピリオドを使用する)
*
* Description. (ピリオドを使用する)
*
* @link   URL
* @file   This files defines the MyClass class.
* @author AuthorName.
* @since  x.x.x
*/
 
/** jshint {ここにインライン構成} */

Top ↑

サポートされる JSDoc タグ サポートされる 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 する。
@mixin mixin オブジェクトをドキュメント
@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 タグ サポートされない 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 を使用。

Top ↑

最新英語版 最新英語版