• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

JavaScript ドキュメント規約

提供: WordPress Codex 日本語版
移動先: 案内検索

注意: この記事は「Core Contributor Handbook」の「JavaScript Documentation Standards」(2016年8月15日時点)の訳です。
最新版については英語版を参照してください。

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

参照: WordPress コーディング規約WordPress インラインドキュメント規約

何をドキュメントするか

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

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

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

ドキュメントのヒント

文体

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

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

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

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

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

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

短い説明:

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

長い説明:

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

@param および @return タグ:

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

行の折り返し

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


関数

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

  • @summary: 関数の目的を説明する簡潔な単一の文。最大でも2行。最後はピリオド。
  • 長い説明: 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 をリストする。
  • @static: クラスに対し、クラスコンストラクタで関数が static メソッドであることを示す。
  • @see: 依存する関数やクラス
  • @link: 詳細情報への URL
  • @fires: 関数から呼ばれるイベント
  • @listens: この関数が期待するイベント
  • @global: 関数内で使用される JavaScript グローバル変数。オプションで変数を説明する。
  • @param: 変数の簡単な説明。JSDoc @param 構文を使用して、変数がオプションかどうかや、デフォルト値等を示す。
  • @return: 注意: 説明の最後はピリオド
/**
 * @summary Short description. (ピリオドを使用)
 *
 * Long. (ピリオドを使用)
 *
 * @since x.x.x
 * @deprecated x.x.x Use new_function_name() を使用。
 * @access private
 *
 * @class
 * @augments superclass
 * @mixes mixin
 *
 * @see Function/class relied on
 * @link URL
 * @global type $varname Short description.
 * @fires target:event
 * @listens target:event
 *
 * @param type $var Description.
 * @param type $var Optional. Description.
 * @return type Description.
 */

オブジェクトプロパティ

オブジェクトプロパティは次のようにフォーマットしてください。

  • 短い説明: 最後はピリオド
  • @since x.x.x: 常に3組の数字(例 @since 3.6.0)
  • @access: 「private」「protected」「public」のどれか。private プロパティは内部使用のみを意味する
  • @property: @param と同様の形式
/**
 * Short description. (ピリオドを使用)
 *
 * @since x.x.x
 * @access (private、protected または public)
 * @property type $var 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 ファイルにヘッダーブロックを記述してください。

必要とされるファイルやライブラリについても @requires タグを使用して短い説明の JSDoc ブロックでドキュメントしてください。

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

/**
 * (ファイルの目的を書いた長い説明をここに書く。
 * ファイル内のすべての機能を詳細に記述する。
 * 説明は複数行にわたっても構わない。最後はピリオドで終わること)
 *
 * @summary   ファイルの短い説明。
 *
 * @link  URL
 * @since x.x.x (もしあれば)
 * @requires javascriptlibrary.js
 * @class
 * @classdesc This is a description of the MyClass class.
 */
 
/** jshint {ここにインライン構成} */

サポートされる 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いつ、この機能は追加されたか?
@static静的メンバーをドキュメント
@summary完全な説明の短い版
@this'this' キーワードはここで何を参照するか?
@throwsどんなエラーがスローされるかを記述
@todo完了すべきタスクをドキュメント
@tutorial同梱されるチュートリアルファイルへのリンクを挿入
@typeオブジェクトの型をドキュメント
@typedefカスタムタイプをドキュメント
@variation同一名で異なるオブジェクトを区別
@versionアイテムのバージョン番号をドキュメント

サポートされない JSDoc タグ

タグ なぜサポートされないか
@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 を使用。
@returnsサポートされないシノニム。代わりに @return を使用。
@exceptionサポートされないシノニム。代わりに @throws を使用。

最新英語版: Core Contributor Handbook > JavaScript Documentation Standards