文書化すべき内容

WordPressにおけるPHPの文書化は、主にフォーマットされた文書ブロックまたはインラインコメントの形を取ります。

以下は、WordPressファイルで文書化すべき内容のリストです:

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

文書化のヒント

言語

要約は明確でシンプル、かつ簡潔であるべきです。要素が存在する「理由」を説明するのではなく、「何を」し、「いつ」それが行われるのかを文書化することに焦点を当ててください。

関数、フック、クラス、またはメソッドは三人称単数の要素であり、各要素が何をするかを説明するために三人称単数動詞を使用する必要があります。

三人称単数動詞の活用を思い出すのに助けが必要ですか？関数、フック、クラス、またはメソッドの要約の前に「それ」を付けて想像してください:

  • 良い: “(それは) 何かを行います。”
  • 悪い: “(それは) 何かを行う。”

要約の例:

  • 関数: 関数は何をしますか？
    • 良い: 投稿の最終更新日を表示します。
    • 悪い: 投稿が最後に更新された日付を表示します。
  • フィルター: 何がフィルタリングされていますか？
    • 良い: 投稿の内容をフィルタリングします。
    • 悪い: 投稿テンプレートに出力される投稿の内容を編集できます。
  • アクション: アクションはいつ発火しますか？
    • 良い: _コアの大部分が読み込まれた後、ユーザーが認証されると発火します。
    • 悪い: _多くのWordPressコアが読み込まれた後にカスタム投稿タイプ、カスタムタクソノミー、およびその他の一般的な管理タスクを登録できます。

文法

記述要素は完全な文として書かれるべきです。この基準の唯一の例外は、ファイルヘッダーの要約であり、これは文よりもファイルの「タイトル」として意図されています。

要約、説明、およびパラメーターまたは戻り値の説明で要素を列挙する際には、連続（オックスフォード）カンマを使用するべきです。

その他

@since: WordPressに何かが追加されたバージョンを検索する際に推奨されるツールは svn blame です。古いフックのための追加リソースは WordPress Hooks Database です。

これらのツールを使用した後にバージョン番号が特定できない場合は、@since Unknownを使用してください。

WPMUから移植されたものはすべて@since MU (3.0.0)を使用する必要があります。既存の@since MU (3.0.0)タグは変更しないでください。

コードリファクタリング: コーディング基準を満たすために文書化されている特定のアクションまたはフィルター行を間隔を空けて配置することは許可されますが、ファイル内の他のコードをリファクタリングしないでください。

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

WordPressのPHPに対するインライン文書化基準は、公式コードリファレンスでの最適な出力のために特別に調整されています。そのため、コアの基準に従い、以下に記載されたフォーマットを遵守することは非常に重要です。

一般

DocBlocksは、フック、アクション、関数、メソッド、またはクラスの行の直前に配置する必要があります。DocBlockと宣言の間に開閉タグやその他のものがあってはならず、パーサーが混乱しないようにします。

要約

要約には、HTMLマークアップやMarkdownのいかなる形式も使用してはいけません。テキストがHTML要素やタグを参照する場合は、「画像タグ」または「img」要素として書かれるべきであり、「<img>」として書かれるべきではありません。例えば:

  • 良い: ヘッダーでリンクタグを印刷する際に発火します。
  • 悪い: ヘッダーで<link>タグを印刷する際に発火します。

インラインPHPDocタグを使用することができます。

説明

HTMLマークアップはコード例の外で使用してはいけませんが、説明の中で必要に応じてMarkdownを使用することができます。

  • 1. リスト:
    ハイフン（-）を使用して順不同リストを作成し、前後に空行を入れます。
    ``````bash
  • Description which includes an unordered list:
    *
      • This is item 1.
      • This is item 2.
      • This is item 3.
        *
    • The description continues on …
      数字を使用して順序付きリストを作成し、前後に空行を入れます。bash
  • Description which includes an ordered list:
    *
      1. This is item 1.
      1. This is item 2.
      1. This is item 3.
        *
    • The description continues on …
      ``````
  • 2. コードサンプルは、コードの各行を4つのスペースでインデントし、前後に空行を入れることで作成されます。コードサンプル内の空行も4つのスペースでインデントする必要があります。この方法で追加された例は<pre>タグで出力され、構文ハイライトされません。
    ``````bash
  • Description including a code sample:
    *
    • $status = array(
    • ‘draft’ => __( ‘Draft’ ),
    • ‘pending’ => __( ‘Pending Review’ ),
    • ‘private’ => __( ‘Private’ ),
    • ‘publish’ => __( ‘Published’ )
    • );
      *
    • The description continues on …
      ``````
  • 3. URLの形式でのリンク、関連するTracチケットや他の文書は、@linkタグを使用してDocBlock内の適切な場所に追加する必要があります:
    ``````bash

@since セクション（変更ログ）

すべての関数、フック、クラス、およびメソッドには、それに関連する@sinceバージョンが必要です（詳細は以下）。

@sinceタグの説明にはHTMLを使用してはいけませんが、必要に応じて限られたMarkdownを使用することができます。たとえば、変数、引数、またはパラメータ名の周りにバックティックを追加する場合などです。例: $variable。

バージョンは3桁のx.x.xスタイルで表現されるべきです: 

  1. * @since 4.4.0

関数、フック、クラス、またはメソッドに重要な変更が加えられた場合、その関数の変更ログを提供するために追加の@sinceタグ、バージョン、および説明を追加する必要があります。

「重要な変更」には、以下が含まれますが、これに限定されません:

  • 新しい引数またはパラメータの追加。
  • 必須引数がオプションになること。
  • デフォルト/期待される動作の変更。
  • 関数またはメソッドが新しいAPIのラッパーになること。
  • 名前が変更されたパラメータ（PHP 8.0のサポートが発表された後）。

PHPDocは、この明示的な理由のためにDocBlocks内で複数の@sinceバージョンをサポートしています。@sinceブロックに変更ログエントリを追加する際には、バージョンを引用し、文の形式で説明を追加し、ピリオドで終わるべきです: 

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

その他の説明

@param、@type、@return: これらのタグの説明にはHTMLを使用してはいけませんが、必要に応じて限られたMarkdownを使用することができます。たとえば、変数の周りにバックティックを追加する場合などです。例: $variable。

  • インライン@seeタグを使用して、コア内のフックを自動リンクすることもできます:
    • フック、例: 'save_post'
    • 動的フック、例: '$old_status_to_$new_status'（引用内の余分な波括弧は削除されています）
  • デフォルトまたは利用可能な値は単一引用符を使用するべきです。例: ‘draft’。翻訳可能な文字列は説明内でそのように識別されるべきです。
  • HTML要素およびタグは「audio要素」または「linkタグ」として書かれるべきです。

行の折り返し

DocBlockテキストは、80文字のテキストの後に次の行に折り返すべきです。DocBlock自体が左に20文字分インデントされている場合、折り返しは100文字の位置で発生する可能性がありますが、合計120文字を超えてはなりません。

DocBlockフォーマット

以下の各セクションに提供されている例は、期待されるDocBlockの内容とタグ、および正確なフォーマットを示しています。DocBlock内ではタブではなくスペースを使用し、各タググループ内の項目が例に従って整列されていることを確認してください。

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

関数およびクラスメソッドは次のようにフォーマットするべきです:

  • 要約: 関数の目的を最大2行で簡潔に説明します。文の最後にはピリオドを使用します。
  • 説明: 要約を補足し、より詳細な説明を提供します。文の最後にはピリオドを使用します。
  • @ignore: 要素が内部使用のみを意図している場合に使用し、パースからスキップされるべきです。
  • @since x.x.x: 常に3桁であるべきです（例: @since 3.9.0）。例外は@since MU (3.0.0)です。
  • @access: コア専用の関数またはクラスが「プライベート」コアAPIを実装する場合にのみ使用されます。要素がプライベートである場合、内部使用の意図を示すメッセージとともに出力されます。
  • @see: 内部で重視される関数、メソッド、またはクラスへの参照です。インライン@seeタグの期待されるフォーマットについては、上記の注意を参照してください。
  • @link: 追加情報を提供するURLです。これは他の関数、フック、クラス、またはメソッドを参照するために使用されるべきではありません。@seeを参照してください。
  • @global: 関数またはメソッド内で使用されるPHPグローバルをリストし、グローバルのオプションの説明を含めます。複数のグローバルがリストされている場合、それらはタイプ、変数、および説明に従って整列されるべきです。
  • @param: パラメータがオプションである場合は、説明の前に「オプション」と記載し、文の最後にはピリオドを含めます。説明には受け入れられる値とデフォルトを含めるべきです。例: オプション。この値は何かを行います。‘post’、‘term’、または空を受け入れます。デフォルトは空です。
  • @return: すべての可能な戻り値の型とそれぞれの説明を含むべきです。文の最後にはピリオドを使用します。注意: @return voidは、デフォルトのバンドルテーマおよびWordPress Coreに含まれるPHP互換シムの外で使用されるべきではありません。 
  1. /**
  2.  * Summary.
  3.  *
  4.  * Description.
  5.  *
  6.  * @since x.x.x
  7.  *
  8.  * @see Function/method/class relied on
  9.  * @link URL
  10.  * @global type $varname Description.
  11.  * @global type $varname Description.
  12.  *
  13.  * @param type $var Description.
  14.  * @param type $var Optional. Description. Default.
  15.  * @return type Description.
  16.  */

1.1 配列の引数

引数の配列であるパラメータは、「発信」関数内でのみ文書化され、対応するDocBlocks内で@seeタグを介して相互参照されるべきです。

配列の値は、Hooksの文書化方法に似たWordPressのハッシュ表記スタイルを使用して文書化されるべきであり、各配列の値は@typeタグで始まり、次の形式を取ります: 

  1. *     @type type $key Description. Default 'value'. Accepts 'value', 'value'.
  2. *                     (aligned with Description, if wraps to a new line)

「発信」関数の例と引数配列の再利用は wp_remote_request|post|get|head() です。 

  1. /**
  2.  * Summary.
  3.  *
  4.  * Description.
  5.  *
  6.  * @since x.x.x
  7.  *
  8.  * @param type  $var Description.
  9.  * @param array $args {
  10.  *     Optional. An array of arguments.
  11.  *
  12.  *     @type type $key Description. Default 'value'. Accepts 'value', 'value'.
  13.  *                     (aligned with Description, if wraps to a new line)
  14.  *     @type type $key Description.
  15.  * }
  16.  * @param type  $var Description.
  17.  * @return type Description.
  18.  */

ほとんどの場合、ハッシュ表記で個々の引数をオプションとしてマークする必要はありません。配列全体が通常オプションであるためです。「オプション。」とハッシュ表記の説明に記載するだけで十分です。配列がオプションでない場合、個々のキー/値ペアがオプションである可能性があり、必要に応じてそのようにマークするべきです。

1.2 非推奨の関数

関数が非推奨であり、もはや使用すべきでない場合、@deprecatedタグとともに、代わりに使用すべきバージョンと説明を追加する必要があります。@seeタグの追加使用に注意してください。コードリファレンスはこの情報を使用して、置き換え関数へのリンクを試みます。 

  1. /**
  2.  * Summary.
  3.  *
  4.  * Description.
  5.  *
  6.  * @since x.x.x
  7.  * @deprecated x.x.x Use new_function_name()
  8.  * @see new_function_name()
  9.  *
  10.  * @param type $var Optional. Description.
  11.  * @param type $var Description.
  12.  * @return type Description.
  13.  */

2. クラス

クラスのDocBlocksは次のようにフォーマットするべきです:

  • 要約: クラスの目的を最大2行で簡潔に説明します。文の最後にはピリオドを使用します。
  • 説明: 要約を補足し、より詳細な説明を提供します。文の最後にはピリオドを使用します。
  • @since x.x.x: 常に3桁であるべきです（例: @since 3.9.0）。例外は@since MU (3.0.0)です。 
  1. /**
  2.  * Summary.
  3.  *
  4.  * Description.
  5.  *
  6.  * @since x.x.x
  7.  */

サブクラスを文書化する場合、スーパークラスへの@seeタグの参照を含めることも役立ちます: 

  1. /**
  2.  * Summary.
  3.  *
  4.  * Description.
  5.  *
  6.  * @since x.x.x
  7.  *
  8.  * @see Super_Class
  9.  */

2.1 クラスメンバー

2.1.1 プロパティ

クラスプロパティは次のようにフォーマットするべきです:

  • 要約: 文の最後にはピリオドを使用します。
  • @since x.x.x: 常に3桁であるべきです（例: @since 3.9.0）。例外は@since MU (3.0.0)です。
  • @var: @paramと同じ方法でフォーマットされますが、説明は省略可能です。 
  1. /**
  2.  * Summary.
  3.  *
  4.  * @since x.x.x
  5.  * @var type $var Description.
  6.  */
2.1.2 定数
  • 要約: 文の最後にはピリオドを使用します。
  • @since x.x.x: 常に3桁であるべきです（例: @since 3.9.0）。例外は@since MU (3.0.0)です。
  • @var: @paramと同じ方法でフォーマットされますが、説明は省略可能です。 
  1. /**
  2.  * Summary.
  3.  *
  4.  * @since x.x.x
  5.  * @var type $var Description.
  6.  */
  7. const NAME = value;

3. requireおよびinclude

必要または含まれるファイルは、要約説明のDocBlockで文書化されるべきです。オプションで、明確さのためにインラインget_template_part()呼び出しにも適用される場合があります。 

  1. /**
  2.  * Summary.
  3.  */
  4. require_once( ABSPATH . WPINC . '/filename.php' );

4. フック（アクションおよびフィルター）

アクションフックとフィルターフックは、do_action()またはdo_action_ref_array()、またはapply_filters()またはapply_filters_ref_array()への呼び出しの直前の行で文書化されるべきであり、次のようにフォーマットされるべきです:

  • 要約: フックの目的を簡潔に説明する1行の説明です。文の最後にはピリオドを使用します。
  • 説明: 要約に対する補足説明が必要な場合は、提供します。
  • @ignore: フックが内部使用のみを意図している場合に使用し、パースからスキップされるべきです。
  • @since x.x.x: 常に3桁であるべきです（例: @since 3.9.0）。例外は@since MU (3.0.0)です。
  • @param: パラメータが引数の配列である場合、各引数をハッシュ表記を使用して文書化し（上記の「配列の引数」セクションで説明）、各行の最後にはピリオドを含めます。 
  3. ``````bash
  4. /**
  5.  * Summary.
  6.  *
  7.  * Description.
  8.  *
  9.  * @since x.x.x
  10.  *
  11.  * @param type  $var Description.
  12.  * @param array $args {
  13.  *     Short description about this hash.
  14.  *
  15.  *     @type type $var Description.
  16.  *     @type type $var Description.
  17.  * }
  18.  * @param type  $var Description.
  19.  */
  20. `

フックがHTMLのブロックや長い条件の中にある場合、DocBlockはHTMLブロックや条件の開始の直前の行に配置されるべきです。たとえそれがHTMLの連続行で行の折り返し/PHPタグを強制することを意味してもです。

フックが追加されたバージョンを検索する際に使用するツールは、svn blameまたは古いフックのためのWordPress Hooks Databaseです。これらのツールを使用した後にバージョン番号が特定できない場合は、@since Unknownを使用してください。

4.1 重複フック

時折、フックが同じまたは別のコアファイルで複数回使用されることがあります。この場合、DocBlock全体を毎回リストするのではなく、アクションまたはフィルターの最初に追加されたまたは最も論理的に配置されたバージョンのみが完全に文書化されます。以降のバージョンには単一行のコメントが必要です。

アクションの場合: 

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

フィルターの場合: 

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

どのインスタンスを文書化するべきかを判断するには、同じフックタグの複数のインスタンスを検索し、svn blameを使用してフックの最初の使用を見つけます。最も早い改訂に基づいています。同じリリースで複数のインスタンスのフックが追加された場合は、「プライマリ」として最も論理的に配置されたものを文書化します。

5. インラインコメント

メソッドや関数内のインラインコメントは次のようにフォーマットするべきです:

5.1 単一行コメント

  1. // Allow plugins to filter an array.

5.2 複数行コメント

  1. /*
  2.  * This is a comment that is long enough to warrant being stretched over
  3.  * the span of multiple lines. You'll notice this follows basically
  4.  * the same format as the PHPDoc wrapping and comment block style.
  5.  */

重要な注意: 複数行コメントは/**（二重アスタリスク）で始めてはいけません。パーサーがそれをDocBlockと誤解する可能性があるためです。代わりに/*（単一アスタリスク）を使用してください。

6. ファイルヘッダー

ファイルヘッダーのDocBlockは、ファイルに含まれる内容の概要を提供するために使用されます。

可能な限り、すべてのWordPressファイルには、ファイルの内容に関係なくヘッダーDocBlockを含めるべきです。これにはクラスを含むファイルも含まれます。 

  1. /**
  2.  * Summary (no period for file headers)
  3.  *
  4.  * Description. (use period)
  5.  *
  6.  * @link URL
  7.  *
  8.  * @package WordPress
  9.  * @subpackage Component
  10.  * @since x.x.x (when the file was introduced)
  11.  */

要約セクションは、ファイルが特定の目的を果たすことを簡潔に説明することを意図しています。

例:

  • 良い: “ウィジェットAPI: WP_Widgetクラス”
  • 悪い: “コアウィジェットクラス”

説明セクションは、特定のファイルがAPIやコンポーネントの全体的な構成にどのように適合するかなど、ファイルの概要情報をより良く説明するために使用できます。

例:

  • 良い: “ウィジェットAPIは、WP_WidgetおよびWP_Widget_Factoryクラスと、ウィジェットおよび関連するサイドバーAPIを実装するさまざまなトップレベルの機能で構成されています。WordPressはデフォルトでいくつかの一般的なウィジェットを登録します。”

7. 定数

定数のDocBlockは、定数の説明を提供し、より良い使用と理解を促進するために使用されます。

定数は次のようにフォーマットするべきです:

  • 要約: 文の最後にはピリオドを使用します。
  • @since x.x.x: 常に3桁であるべきです（例: @since 3.9.0）。例外は@since MU (3.0.0)です。
  • @var: @paramと同じ方法でフォーマットされます。説明は省略可能です。 
  1. /**
  2.  * Summary.
  3.  *
  4.  * @since x.x.x (if available)
  5.  * @var type $var Description.
  6.  */

PHPDocタグ

WordPressで使用される一般的なPHPDocタグには、@since、@see、@global、@param、および@returnが含まれます（完全なリストは下の表を参照）。

ほとんどの場合、タグは正しく使用されていますが、常にそうではありません。たとえば、時々@linkタグがインラインで見られ、別の関数やメソッドにリンクしています。「リンク」することは必要ありません。コードリファレンスはこれらの要素を自動的にリンクします。インラインでフックを「リンク」する場合、使用すべき適切なタグは@seeです。その他の説明セクションを参照してください。

タグ 使用法 説明
@access private 限られた状況でのみ使用され、可視性修飾子がコードで使用できない場合、かつプライベートである場合、コア専用の関数やコアクラスが「プライベート」APIを実装する場合に使用されます。ブロック内の@since行の直下に使用されます。
@deprecated version x.x.x 使用 replacement function name instead 関数/メソッドが非推奨になったWordPressのバージョン。3桁のバージョン番号を使用する必要があります。対応する@seeタグを伴うべきです。
@global datatype $variable description 関数/メソッドで使用されるグローバルを文書化します。ブール型および整数型の場合、boolおよびintをそれぞれ使用します。
@internal information string 通常、内部使用のためのノートを追加するために{}でラップされて使用されます。
@ignore (standalone) 要素全体のパースをスキップするために使用されます。
@link URL 関数/メソッドに関する追加情報へのリンク。外部スクリプト/ライブラリの場合、ソースへのリンク。関連する関数/メソッドには使用しないでください。@seeを使用してください。
@method returntype description クラス内に見つかる「マジック」メソッドを示します。
@package packagename ファイル内のすべての関数、インクルード、および定義が属するパッケージを指定します。ファイルの先頭のDocBlockに見られます。コア（およびバンドルテーマ）では、これは常にWordPressです。
@param datatype $variable description パラメータの形式: パラメータタイプ、変数名、説明、デフォルト動作。ブール型および整数型の場合、boolおよびintをそれぞれ使用します。
@return datatype description 関数またはメソッドの戻り値を文書化します。@return voidはデフォルトのバンドルテーマの外で使用されるべきではありません。ブール型および整数型の場合、boolおよびintをそれぞれ使用します。
@see elementname 関数/メソッドが依存する別の関数/メソッド/クラスを参照します。インラインでフックを「リンク」するためにのみ使用されるべきです。
@since version x.x.x 関数/メソッドが追加されたリリースバージョンを文書化します。3桁のバージョン番号を使用します。これはバージョン検索を助けるためのものであり、コード内でバージョンを比較する際に使用されます。例外は@since MU (3.0.0)です。
@static (standalone) 注意: このタグは過去に使用されていましたが、もはや使用されるべきではありません。コード内でstaticキーワードを使用するだけで、phpDocumentorはPHP5+で静的変数およびメソッドを認識し、PhpDocumentorはそれらを静的としてマークします。
@staticvar datatype $variable description 注意: このタグは過去に使用されていましたが、もはや使用されるべきではありません。関数/メソッド内での静的変数の使用を文書化します。ブール型および整数型の場合、boolおよびintをそれぞれ使用します。
@subpackage subpackagename ページレベルのDocBlockの場合、ファイル内のすべての関数および定義が属するコンポーネントを指定します。クラスレベルのDocBlockの場合、クラスが属するサブパッケージ/コンポーネントを指定します。
@todo information string 実装されていない要素の計画された変更を文書化します。
@type datatype description for an argument array value 引数配列値の型を示すために使用されます。例の構文については、フックまたは配列の引数セクションを参照してください。
@uses class::methodname() / class::$variablename / functionname() 注意: このタグは過去に使用されていましたが、もはや使用されるべきではありません。使用される主要な関数/メソッドを参照します。短い説明を含む場合があります。
@var datatype description クラス変数のデータ型と短い説明。コールバックはコールバックとしてマークされます。

PHPDocタグは、一部のテキストエディタ/IDEと連携して、コードの一部に関する詳細情報を表示します。これにより、これらのエディタを使用する開発者が目的を理解し、コード内でどこで使用するかを理解するのに役立ちます。PhpStormとNetbeansはすでにPHPDocをサポートしています。

以下のテキストエディタ/IDEには、DocBlocksを自動生成するのに役立つ拡張機能/バンドルがあります:

注意: DocBlocksを生成するのに助けがあっても、ほとんどのコードエディタは非常に徹底した仕事をしません。生成されたDocBlocksの特定の領域を手動で埋める必要がある可能性が高いです。

非推奨タグ

前書き: 現時点では、一貫性のために、WordPress Coreは新しいDocBlocksを書く際や古いDocBlocksを編集する際に@subpackageタグを引き続き使用します。

新しい外部PSR-5の推奨事項が最終決定されるまで、特定のタグを非推奨にするなどの全体的な変更は検討されません。
新しいPSR-5の推奨事項に提案されているように、以下のPHPDocタグは非推奨にされるべきです:

  • @subpackage（統一されたパッケージタグ: @package Package\Subpackageに代わって）
  • @static（もはや必要ない）
  • @staticvar（もはや必要ない）

その他のタグ

@packageタグのプラグインおよびテーマ（バンドルテーマを除く）

サードパーティのプラグインおよびテーマの著者は、プラグインやテーマ内で@package WordPressを使用してはなりません。プラグインの@package名はプラグイン名であるべきです。テーマの場合は、テーマ名をアンダースコアで区切って使用するべきです: Twenty_Fifteen。

@authorタグ

WordPressの方針として、@authorタグを使用しないことになっています。外部ライブラリの維持を除いてです。コードへの「所有権」を示唆することは、貢献を妨げる可能性があるためです。

@copyrightおよび@licenseタグ

@copyrightおよび@licenseタグは外部ライブラリやスクリプトで使用され、WordPressコアファイルでは使用されるべきではありません。

  • @copyrightは外部スクリプトの著作権を指定するために使用されます。
  • @licenseは外部スクリプトのライセンスを指定するために使用されます。

リソース