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

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

PHP ドキュメント規約

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

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

WordPress では PHPDoc をベースにしたカスタムのドキュメントスキーマを使用しています。PHPDoc は現在、策定中の PHP プログラム用のドキュメント標準です。phpDocumentor によって管理されています。

一部の規則、たとえば WordPress のハッシュ記法の実装などでは ドラフト版 PSR-5 recommendations から規約を採用していますが、現時点で WordPress が 「PSR-5 互換」を目指しているわけではありません。単に「ある部分」で PSR-5 recommendations を採用したに過ぎません。

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

何をドキュメントするか

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

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

  • 関数、およびクラスのメソッド
  • クラス
  • クラスのメンバー (プロパティや定数を含む)
  • require と include
  • アクションフックとフィルターフック
  • インラインコメント
  • ファイルヘッダー

ドキュメントのヒント

文体

「Summary」(概要) を書く場合には、明確でシンプルな、短い文を心がけてください。ドキュメントする要素が「なぜ」存在するのかではなく、「いつ」「何を」実行するのかを記述してください。

関数、フック、クラス、メソッドは「三人称単数」の要素です。説明を記述する場合も「三人称単数の動詞」を使用してください。

ヒント: 三人称単数の動詞の活用に悩む場合は、関数、フック、クラス、メソッドの Summary を書く際、先頭に「It」をつけて考えてください。
- : "(It) Does something."
- : "(It) Do something."

Summary の例:

  • 関数: 「何を」するのか?
    • 正: Displays the last modified date for a post. (投稿の最終更新日を表示する)
    • 誤: Display the date on which the post was last modified. (投稿が最後に更新された日を表示)
  • フィルター: 「何を」フィルターするのか?
    • 正: Filters the post content. (投稿の内容をフィルターする)
    • 誤: Lets you edit the post content that is output in the post template. (投稿の内容を編集し、投稿テンプレートの出力とします)
  • アクション: 「いつ」呼ばれるのか?
    • 正: Fires after most of core is loaded, and the user is authenticated. (コアの大部分がロードされ、ユーザーの認証後に呼ばれる)
    • 誤: Allows you to register custom post types, custom taxonomies, and other general housekeeping tasks after a lot of WordPress core has loaded. (大部分の WordPress コアがロードされた後で、カスタム投稿タイプ、カスタムタクソノミー、その他の汎用の整理用タスクを登録できます)

文法

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

概要、説明、パラメータや戻り値の説明内で複数の要素を書く際には serial comma (Oxford comma) を使用してください。(例: A, B and C)

その他

@since: WordPress に追加されたバージョン番号等を調べるには「svn blame」の使用を推奨します。補完するツールとして古いフックの場合には「WordPress Hooks Database」も使用してください。

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

WPMU からの移植は「@since MU」を使用してください。既存の「@since MU」タグは変更しないでください。

コードのリファクタリング: コーディング規約に合わせるため特定のアクションやフックの行にスペースを挿入、削除しても構いませんが、ファイルの他の部分はリファクタリングしないでください。

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

重要: WordPress の「PHP インラインドキュメント規約」は最適な「公式コードリファレンス」が出力されるよう調整されています。コア内で規約に準拠し、以下の説明どおりにドキュメントをフォーマットすることは正しい出力のために極めて重要です。

全般

DocBlock はフック、アクション、関数、メソッド、クラスの行の直前に記述してください。DocBlock とこれらの定義との間には開始タグ、終了タグを含め何も書かないでください。パーサーが混乱します。

Summary (旧称 Short Description)

Summary では HTML、Markdown、その他のマークアップを使用しないでください。HTML 要素やタグに触れる場合は、「image tag」または「img element」と記述してください。「<img>」は使わないでください。

  • 正: Fires when printing the link tag in the header.
  • 誤: Fires when printing the <link> tag in the header.

インライン PHPDoc タグは使用できます。

Description (旧称 Long Description)

コードの例以外では HTML マークアップを使用しないでください。Markdown は必要に応じて使用できます。

1. リスト

順序のないリストの場合はハイフン「-」を使用してください。リストの前後には空白行を置いてください。

* Description which includes an unordered list:
*
* - This is item 1.
* - This is item 2.
* - This is item 3.
*
* The description continues on ...

順序付きのリストの場合は数字を使用してください。リストの前後には空白行を置いてください。

* Description which includes an ordered list:
*
* 1. This is item 1.
* 2. This is item 2.
* 3. This is item 3.
*
* The description continues on ...

2. コードの例では、すべての行を4個のスペースでインデントし、コード全体の前後には空白行を置いてください。コードの途中の空白行は、4個のスペースでインデントしてください。なおこの方法で追加された例は <pre> タグで出力され、シンタックスハイライトは適用されません。

* Description including a code sample:
*
*    $status = array(
*        'draft'   => __( 'Draft' ),
*        'pending' => __( 'Pending Review' ),
*        'private' => __( 'Private' ),
*        'publish' => __( 'Published' )
*    );
*
* The description continues on ...

3. 関連する Trac チケットや他のドキュメントへの URL 形式のリンクは DocBlock 内の適切な場所に @link タグを使用して追加してください。

* Description text.
*
* @link https://core.trac.wordpress.org/ticket/20000

@since セクション (変更履歴)

すべての関数、フック、クラス、メソッドには関連する @since バージョンを記述してください。詳細は後述します。

@since タグの説明で HTML は使えません。いくつかの Markdown は必要に応じて使用できます。たとえば変数名、引数名、パラメータ名をバッククォートで囲むことができます。例: `$variable`

バージョンは 3組の数字「x.x.x」 で記述してください。

* @since 4.4.0

関数、フック、クラス、メソッドに重きな変更がある場合には、機能の変更履歴を残す意味で追加の @since タグ、バージョン、説明を加えてください。

たとえば「重大な変更」には以下のような項目が含まれますが、これらに限りません。

  • 新しい引数やパラメータの追加
  • 必須の引数がオプションになった
  • デフォルトや期待する振る舞いの変更
  • 関数やメソッドが新しい API のラッパーになった

以上の説明で明らかですが PHPDoc は DocBlock 内に複数の @since バージョンをサポートします。@since ブロックに変更履歴の行を追加する場合は、バージョンに続けて、大文字で始め、ピリオドで終わる完全な文として説明を追加してください。

* @since 3.0.0
* @since 3.8.0 Added the `post__in` argument.
* @since 4.1.0 The `$force` parameter is now optional.

他の説明

タグの説明で HTML は使えません。いくつかの Markdown は必要に応じて使用できます。たとえばバッククォートで変数名を囲むことができます。例: `$variable`

  • インライン @see タグも、コア内でフックに自動的にリンクする目的で使用できます。
    • フック。例: {@see 'save_post'}
    • 動的なフック。例: {@see '$old_status_to_$new_status'} (注意: シングルクォート内の余分なブレースは除去されています)
  • デフォルト値や指定可能な値にはシングルクォートを使用してください。例:「'draft'」。翻訳対象の文字列は説明内で明示してください。
  • HTML 要素やタグは「audio element」や「link tag」のように記述してください。

行の折り返し

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

DocBlock フォーマット

以下の各セクションの例では、期待する DocBlock の内容とタグを正しいフォーマットで記述しています。DocBlock の中ではタブでなく、スペースを使用してください。各タググループの内容は例と同様に並べてください。

1. 関数およびクラスのメソッド

関数およびクラスのメソッドは次のようにフォーマットしてください。

  • Summary(概要): 関数の目的を説明する簡潔な単一の文。最大でも2行。最後はピリオド。
  • Description(説明): Summary を補足する詳細な説明。文の最後はピリオド。
  • @ignore: 要素は内部でのみ使用され、パースの対象外とする場合に使用。
  • @since x.x.x: 常に3組の数字(例 @since 3.9.0)。例外は @since MU
  • @access: スタンドアローン関数では private の場合のみ使用。関数が private の場合、内部使用の関数とメッセージが出力されます。
  • @see: 強く依存する関数、メソッド、クラスへの参照。インライン @see タグの期待するフォーマットについては上の注意を参照。
  • @link: 追加の情報用の URL。別の関数、フック、クラス、メソッドへの参照の場合には使わないでください。@see 参照。
  • @global: 関数またはメソッド内で使用される PHP グローバル変数。オプションでグローバル変数の説明も記述できます。複数のグローバル変数がある場合、型、変数、説明ごとに並べてグループ分けしてください。
  • @param: オプションであれば説明の前に「Optional」と付けてください。最後はピリオドです。説明には指定可能な値の範囲、デフォルト値も含めてください。例: Optional. This value does something. Accepts ‘post', ‘term', or empty. Default empty.
  • @return: すべての戻り値の型とその説明を記述してください。最後はピリオです。注意: WordPress 本体に同梱されるテーマ以外では、@return void は使用しないでください。
/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 * @access (関数の場合、private の場合のみ使用)
 *
 * @see Function/method/class relied on
 * @link URL
 * @global type $varname Description.
 * @global type $varname Description.
 *
 * @param type $var Description.
 * @param type $var Optional. Description. Default.
 * @return type Description.
 */

1.1 配列パラメータ

引数の配列をパラメータに取る場合には、最初の送信を行う関数でのみドキュメントし、関連する関数の DocBlock 内では @see タグを使用して相互参照してください。

配列値のドキュメントでは、フックのドキュメントと同じ WordPress 流のハッシュ記法スタイルを使用してください。各配列の値は @type タグで始め、次の形式をとります。

*     @type type $key Description. Default 'value'. Accepts 'value', 'value'.
*                     (複数行の場合は、Description で並べる)

最初の送信を行う関数と、配列引数の再利用については wp_remote_request|post|get|head() を参照してください。

/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x 
 * @access (関数の場合、private の場合のみ使用)
 *
 * @param type  $var Description.
 * @param array $args {
 *     Optional. An array of arguments.
 *
 *     @type type $key Description. Default 'value'. Accepts 'value', 'value'.
 *                     (複数行の場合は、Description で並べる)
 *     @type type $key Description.
 * }
 * @param type  $var Description.
 * @return type Description.
 */

ほとんどの場合、ハッシュ記法内の個々の引数に「Optional.」を付ける必要はありません。これは配列全体がオプションの場合が多いためです。配列がオプションでなく必須の場合で、個々の key と value がオプションの場合には、必要に応じて「Optional.」を記述してください。

1.2 非推奨の関数

関数が非推奨となり、今後使用されない場合には、@deprecated タグを使用し、バージョンと代替の関数を記述してください。注意: これは @see タグの別の用法です。コードリファレンスではこの情報を使用して代替の関数へのリンクを作成します。

/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 * @deprecated x.x.x Use new_function_name()
 * @see new_function_name()
 *
 * @param type $var Optional. Description.
 * @param type $var Description.
 * @return type Description.

2. クラス

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


  • Summary(概要): クラスの目的を説明する簡潔な単一の文。最大でも2行。最後はピリオド。
  • Description(説明): Summary を補足する詳細な説明。最後はピリオド。
  • @since x.x.x: 常に3組の数字(例 @since 3.9.0)。例外は @since MU
/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 */

子クラスのドキュメントでは、@see タグを使用して親クラスへの参照を含めてください。

/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 *
 * @see Super_Class
 */

2.1 クラスのメンバー

2.1.1 プロパティ

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

  • Summary(概要): 最後はピリオド。
  • @since x.x.x: 常に3組の数字(例 @since 3.9.0)。例外は @since MU
  • @access: 「private」「protected」「public」のどれか
  • @var: @param と同様の形式。ただし説明は省略可能
/**
 * Summary.
 *
 * @since x.x.x
 * @access (private、protected または public)
 * @var type $var Description.
 */
2.1.2 定数
  • Summary(概要): 最後はピリオド。
  • @since x.x.x: 常に3組の数字(例 @since 3.9.0)。例外は @since MU
  • @var: @param と同様の形式。ただし説明は省略可能
/**
 * Summary.
 *
 * @since x.x.x
 * @var type $var Description.
 */
const NAME = value;

3. require と include

require または include するファイルは、概要説明の DocBlock でドキュメントしてください。オプションで必要に応じて、インライン get_template_part() から呼び出すファイルもドキュメントしてください。

/**
 * Summary.
 */
require_once( ABSPATH . WPINC . '/filename.php' );

4. アクションフックとフィルターフック

アクションフックもフィルターフックも、do_action()do_action_ref_array()、または apply_filters()apply_filters_ref_array() 呼び出し行の直前でドキュメントしてください。次のようにフォーマットしてください。

  • Summary(概要): フックの目的を説明する簡潔な単一の文。最後はピリオド。
  • Description(説明): 必要な場合は Summary を補足する詳細な説明。
  • @ignore: フックは内部でのみ使用され、パースの対象外とする場合に使用。
  • @since x.x.x: 常に3組の数字(例 @since 3.9.0)。例外は @since MU
  • @param: パラメータが引数の配列であれば、ハッシュ記法を使用して各引数をドキュメント。詳細は「1.1 配列パラメータ」参照。各行の最後はピリオド。

注意: フックのドキュメントに @return は使用しません。アクションフックは何も返さず、フィルターフックは常に第1パラメータを返すためです。

/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 *
 * @param type  $var Description.
 * @param array $args {
 *     Short description about this hash.
 *
 *     @type type $var Description.
 *     @type type $var Description.
 * }
 * @param type  $var Description.
 */

フックが HTML ブロックや長い条件の途中にある場合、DocBlock は HTML ブロックや条件の開始行の直前に置いてください。この結果、連続した HTML 行の途中に改行や PHP タグを含める形になっても構いません。

フックが追加されたバージョンを調べるには「svn blame」、または古いフックの場合には「WordPress Hooks Database」を使用してください。ツールを使用してもバージョン番号を特定できない場合は、@since Unknown を使用してください。

4.1 重複したフック

フックはしばしば同じコアファイル内、異なるコアファイルで複数回使用されます。このような場合は毎回、完全な DocBlock 全体を書くのではなく、アクションフックやフィルターフックが最初に登場した場所、あるいはもっとも論理的な場所で完全にドキュメントし、残りの場所には単一行コメントを加えてください。

アクションフックの場合

/** This action is documented in path/to/filename.php */

フィルターフックの場合

/** This filter is documented in path/to/filename.php */

どのインスタンスをドキュメントすべきかを決めるには、すべてのフックタグの登場を svn blame で検索し、最初に使用されるリビジョンを見つけてください。複数のインスタンスが同時に同じリリースで登場した場合はもっとも論理的な場所を「代表」としてドキュメントしてください。

5. インラインコメント

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

5.1 単一行コメント

// Allow plugins to filter an array.

5.2 複数行コメント

/* 
 * This is a comment that is long enough to warrant being stretched over
 * the span of multiple lines. (基本的に PHPDoc の折り返しやコメント
 * ブロックのスタイルと同じフォーマットであることに注意)
 */

重要な注意: 複数行コメントを「/**」(2つの星印) で始めないでください。パーサーが DocBlock と間違えます。代わりに「/*」(1つの星印) で始めてください。

6. ファイルヘッダー

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

可能であれば常にすべての WordPress ファイルにヘッダー DocBlock を記述してください。ファイルの内容に関わらず、またクラスを定義するファイルも含めすべてのファイルが対象です。

/**
 * Summary (ファイルヘッダーの場合はピリオドなし)
 *
 * Description. (ピリオドを使用)
 *
 * @link URL
 *
 * @package WordPress
 * @subpackage Component
 * @since x.x.x (いつファイルが作成されたか)
 */

Summary セクションではファイルが具体的に「何を」提供するのかを簡潔に説明してください。

例:

  • 正: "Widgets API: WP_Widget class"
  • 誤: "Core widgets class"

Description セクションではファイルの概要をより詳細に説明します。たとえば API やコンポーネント全体におけるファイルの位置づけなどです。

例:

  • 正: "The Widgets API is comprised of the WP_Widget and WP_Widget_Factory classes in addition to a variety of top-level functionality that implements the Widgets and related sidebar APIs. WordPress registers a number of common widgets by default."

7. 定数

定数の DocBlock では、定数の理解と利用のための説明を加えます。

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

  • Summary(概要): 最後はピリオド。
  • @since x.x.x: 常に3組の数字(例 @since 3.9.0)。例外は @since MU
  • @var: @param と同様の形式。ただし説明は省略可能
/**
 * Summary.
 *
 * @since x.x.x (可能であれば)
 * @var type $var Description.
 */

PHPDoc タグ

WordPress で使用される主な PHPDoc タグには @since@see@global@param@return があります。完全なリストについては以下の表を参照してください。

ほとんどの場面でタグは正しく使用されていますが、誤用されている場合もあります。例えばインラインの @link タグは、別の関数やメソッドへのリンクで使用される場合がありますが、実際には既知のクラス、メソッド、関数へのリンクはコードリファレンスが自動で作成するため不要です。インラインでフックをリンクする際の正しいタグは @see です。「他の説明」節も参照してください。

タグ 用法 説明
@access public

private

protected
関数やメソッドのアクセス制御を示す。

@access private は関数がリファレンス化されないことを示す。

ブロック内では @since 行の直後に使用される。
@deprecated version x.x.x 代替の関数名 関数やメソッドがどの WordPress バージョンで非推奨になったかを示す。3組の数字を使用。該当する @see タグを付ける。
@global 型 global

$変数名

説明
関数やメソッドで使用されるグローバル変数をドキュメントする。boolean または integer 型の場合、それぞれ boolint を使用する。
@internal 説明文 典型的な用法として内部利用のみであることを明記する。
@ignore (単体) 要素全体のパースをスキップする
@link URL 関数やメソッドの追加情報へのリンク。

外部のスクリプトやライブラリーにリンクする場合は、ソースにリンクする。

関連する関数やメソッドには使用せず、代わりに @see を使用する。
@method 戻り値の型 説明 クラス内にあるマジックメソッドを記述する。
@package パッケージ名 すべての関数、インクルード、ファイル内の定義が属するパッケージを指定する。ファイル先頭の DocBlock に位置する。コアおよび同梱されるテーマでは常に「WordPress」。
@param データ型 $variable 説明 関数やメソッドのパラメータ。フォーマット: パラメータの型 変数名 説明 デフォルトの動き。boolean および integer 型の場合、それぞれ boolint を使用。
@return データ型 説明 関数やメソッドの戻り値をドキュメントする。WordPress 本体に同梱されるテーマ以外では、@return void は使用しない。boolean および integer 型の場合、それぞれ boolint を使用。
@see 要素名 関数やメソッドが依存する別の関数、メソッド、クラスへの参照。フックとのリンクでのみインラインでの使用可。
@since version x.x.x 関数やメソッドが追加されたリリースバージョンをドキュメントする。バージョンでの検索の容易性、およびコードでのバージョン比較のため、3組の数字のバージョン番号を使用する。例外は @since MU
@subpackage サブパッケージ名 ページレベルの DocBlock の場合、ファイル内のすべての関数や定義が属するコンポーネントを指定する。クラスレベルの DocBlock の場合、クラスが属するサブパッケージやコンポーネントを指定する。
@todo 説明文 現在はまだ未実装だが、将来予定されている要素の変更をドキュメントする。
@type データ型 引数配列値の説明 引数配列値の型を示すために使用する。構文例については「4. アクションフックとフィルターフック」節または「1.1 配列パラメータ」節を参照
@uses クラス::メソッド名()

クラス::$変数名

関数名()
注意: このタグは以前使われていたもの。使用しない。 内部で使用している重要な関数やメソッドを参照する。短い説明を含めてもよい。
@var データ型 説明 クラス変数のデータ型と短い説明。コールバックには「callback」を付ける。

ヒント: テキストエディターや IDE の中には PHPDoc タグを解釈し、コードに関する詳細な情報を表示するものもあります。開発者は各要素の目的が何か、コードのどこで使用するかを容易に理解できます。PhpStorm と Netbeans は PHPDoc をサポートしています。

次のテキストエディターや IDE では DocBlock の自動作成を支援するエクステンションや部品をインストールできます。
- Notepad++: DocIt for Notepad++ (Windows)
- TextMate: php.tmbundle (Mac)
- SublimeText: sublime packages (Windows, Mac, Linux)

注意: DocBlock 生成エクステンション等を使用しても、大部分のコードエディターの出力は完全ではありません。生成された DocBlock を手動で調整する必要があります。

非推奨のタグ

はじめに: WordPress コアは新しい DocBlock の記述でも、古いタグの編集でも、しばらくは過去との一貫性のため @subpackage タグを使用します。

外部で策定中の新しい PSR-5 recommendations 完成後に、タグを非推奨にする等の全体的な変更が検討される予定です。

新しい PSR-5 recommendations の提案では、次の PHPDoc タグは非推奨になる予定です。

  • @subpackage (@package タグへ統合の予定: @package Package\Subpackage)

別のタグ

プラグインやテーマでの @package タグ (同梱されるテーマは除く)

サードパーティのプラグイン作成者やテーマ作成者は、自身のプラグインやテーマに「@package WordPress」を使わないでください。プラグインの @package 名はプラグイン名です。テーマであればテーマ名です。このときスペースは下線で置き換えてください。例: Twenty_Fifteen

@author タグ

外部ライブラリでメンテナンスされている場合を除き、 WordPress のポリシーとして @author タグは使用しません。コードに対しては貢献の妨げになるような、いかなる「所有」的なものも含めません。

@copyright タグと @license タグ

@copyright タグと @license タグは外部ライブラリやスクリプトに使用されます。WordPress コアファイルには使用しません。

  • @copyright は外部スクリプトの著作権を明示する場合に使用する。
  • @license 外部スクリプトのライセンスを明示する場合に使用する。

リソース


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