PHP ドキュメント規約

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

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 (3.0.0)」を使用してください。既存の「@since MU (3.0.0)」タグは変更しないでください。

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

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

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

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

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

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

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

1. リスト

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

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

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

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

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

 * @since 4.4.0

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

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

• 新しい引数やパラメータの追加
• 必須の引数がオプションになった
• デフォルトや期待する振る舞いの変更
• 関数やメソッドが新しい API のラッパーになった
• 名前が変更されたパラメータ (いったん PHP 8.0 のサポートが発表された)

以上の説明で明らかですが 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.

@param、@type、@return: タグの説明で 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 の中ではタブでなく、スペースを使用してください。各タググループの内容は例と同様に並べてください。

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

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

/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 *
 * @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.
 */

引数の配列をパラメータに取る場合には、最初の送信を行う関数でのみドキュメントし、関連する 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 
 *
 * @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.」を記述してください。

関数が非推奨となり、今後使用されない場合には、@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.
 */

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

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

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

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

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

2.1.1 プロパティ

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

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

/**
 * Summary.
 *
 * @since x.x.x
 * @var type $var Description.
 */

2.1.2 定数

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

/**
 * Summary.
 *
 * @since x.x.x
 * @var type $var Description.
 */
const NAME = value;

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

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

アクションフックもフィルターフックも、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 (3.0.0)。
• @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 を使用してください。

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

アクションの場合

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

フィルターの場合

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

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

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

// Allow plugins to filter an array.

/*
 * 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 PHPDoc wrapping and comment block style.
 */

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

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

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

/**
 * Summary (no period for file headers)
 *
 * Description. (use period)
 *
 * @link URL
 *
 * @package WordPress
 * @subpackage Component
 * @since x.x.x (when the file was introduced)
 */

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.”

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

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

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

/**
 * Summary.
 *
 * @since x.x.x (可能であれば)
 * @var type $var Description.
 */

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

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

ヒント: テキストエディターや 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)
• @static (不要になった)
• @staticvar (不要になった)

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

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

@author タグ

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

@copyright タグと @license タグ

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

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

• Wikipedia
• PEAR Standards
• phpDocumentor
• phpDocumentor Tutorial Tags
• ドラフト版 PSR-5 recommendations
• ドラフト版 PSR-19 recommendations

原文

最終更新日: 2024年8月23日