— y2sunlight 2020-07-28
本章は、若干の補足を加筆してはいるものの単にPSRのサイトを日本語に翻訳したものに過ぎません。英語が堪能な方は原文をご参照下さい。翻訳に当たっては、基本的に機械翻訳を使い、理解できない部分は独断で意訳しております。拙い訳では御座いますが恥を忍んで投稿しておりますので、ご指摘など御座いましたらコメントを頂ければ幸いです。
関連記事
— 原文より翻訳 PSR-19: PHPDoc tags 2020-09-01 現在
このPSRの主な目的は、PHPDoc規約でのタグの完全なカタログを提供することです。
SHALL NOT )。SHALL NOT )。このドキュメントは、構文と意図の正式な仕様に限定されています。
このドキュメントのキーワード MUST , MUST NOT , REQUIRED , SHALL , SHALL NOT , SHOULD , SHOULD NOT , RECOMMENDED , MAY 及び OPTIONAL は、 RFC 2119で説明されているように解釈して下さい。
RFC 2119の説明
MUST,REQUIRED,SHALL— 絶対必要
MUST NOT,SHALL NOT— 絶対禁止
SHOULD,RECOMMENDED— 推奨（但し、無視できる特定の正当な理由が存在するかもしれない）
SHOULD NOT— 推奨できない（但し、許可できる特定の正当な理由が存在するかもしれない）
MAY,OPTIONAL— オプション
PHPDoc PSR(PSR-5)の定義セクション(3.Definitions) を参照してください。これらの定義もここで適用されます。
「構造的要素」を実装、拡張、またはオーバーライドする「構造的要素」に関連付けられた PHPDoc には、実装、拡張、またはオーバーライドされた「構造的要素」に関連付けられた PHPDoc から情報の一部を継承する機能があります。
「構造的要素」のすべてのタイプのための PHPDoc は、次の部分が存在しない場合、その部分を継承する必要があります( MUST )：
「構造的要素」の各タイプのための PHPDoc は、関連付けられている「構造的要素」に応じて、タグの特殊なサブセットも継承する必要があります( MUST )。
PHPDoc が Summary や Description などの部分を備えておらず、スーパー要素の PHPDoc に存在する場合、その部分は常に暗黙的に継承されます。以下は、DocBlock がスーパー要素の DocBlock から情報を継承できるすべての要素のリストです：
例えば：
メソッド\SubClass::myMethod()があり、そのクラス\SubClassがクラス\SuperClassを拡張するとします。そしてクラス\SuperClassには同じ名前のメソッドがあります（例：\SuperClass::myMethod）。
上記が当てはまる場合、\SubClass::myMethod()のDocBlockは、\SuperClass::myMethodの PHPDoc から上記の部分を継承します。従って、@versionタグが再定義されなかった場合、\SubClass::myMethod()がスーパー要素と同じ@versionタグを持つと想定されます。
継承は、クラス階層グラフのルートからそのリーフまで行われます。これは、ツリーの下部で継承されたものは、オーバーライドされない限り、上部まで「バブル」する必要がある( MUST )ことを意味します。
継承は暗黙的であるため、「構造的要素」に PHPDoc を含める必要がない場合があります。PHPDoc が故意に省略されたかどうか、またはコードの作成者がドキュメントを追加するのを忘れたかどうかが曖昧になるため、これにより混乱が生じる可能性があります。
この曖昧さを解決するために、@inheritDoc タグを使用して、この要素がスーパー要素から情報を継承することを示すことができます。
例：
/** * This is a summary. */ class SuperClass { } /** * @inheritDoc */ class SubClass extends SuperClass { }
上記の例では、SubClass の Summary は SuperClass 要素の Summary と等しいと見なすことができます。つまり、「This is a summary.」です。
スーパー要素の Description を継承し、独自のテキストを追加して、「構造的要素」に固有の情報を提供したい場合があります。これは、{@inheritDoc} インラインタグを使用して行う必要があります( MUST )。
{@inheritDoc} インラインタグは、その場所にスーパー要素の説明を挿入または推測する必要があることを示します( MUST )。
例：
/**
* これは、この要素のSummaryです。
*
* {@inheritDoc}
*
* さらに、この説明には、この要素に固有の詳細な情報を提供する詳細情報が含まれます。
*/
上記の例では、この PHPDoc の Description は、{@inheritDoc} インラインタグで示されるスーパー要素の Description と、それに続く本文テキストの組み合わせであることを示しています。
この章の最初で定義されているように、継承された説明とタグに加えて、関数または、クラスまたはインターフェースのメソッドは、次のタグを継承する必要があります( MUST )：
説明で特に言及されていない限り、各「DocBlock」で各タグが0回以上発生する場合があります( MAY )。
@api タグは、「構造的要素」をパッケージの主要なパブリックAPIの一部として強調するために使用されます。
@api
@api タグを公開されている「構造的要素」に適用して、生成されたドキュメントでそれらを強調し、ライブラリまたはフレームワークの主要な公開APIコンポーネントをコンシューマーに示すことができます( MAY )。
公開されている他の「構造的要素」は、生成されたドキュメントではそれほど目立たないように記載されている場合があります( MAY )。
@internalも参照してください。これは、生成されたドキュメントから内部APIコンポーネントを非表示にするために使用できます( MAY )。
class UserService { /** * このメソッドは公開APIです。 * * @api */ public function getUser() { <...> } /** * このメソッドは「パッケージスコープ」ですが、公開APIではありません */ public function callMefromAnotherClass() { <...> } }
@author タグは、「構造的要素」の作成者を文書化するために使用されます。
@author [name] [<email address>]
@author タグを使用して、「構造的要素」を作成した人、または「構造的要素」に大幅な変更を加えた人を示すことができます。このタグには、電子メールアドレスも含まれている場合があります( MAY )。電子メールアドレスを指定する場合は、作成者名の後に山かっこ( < > )で囲む必要があり( MUST )、RFC 2822 で定義されている構文に準拠する必要があります( MUST )。
/**
* @author My Name
* @author My Name <my.name@example.com>
*/
@copyrightタグは、「構造的要素」の著作権情報を文書化するために使用されます。
@copyright <description>
@copyright タグは、「構造的要素」の著作権者を定義します。このタグで示された著作権は、特に明記されていない限り、それが適用される「構造的要素」とすべての子要素に適用されます。
説明の形式は、個々のプロジェクトのコーディング規約に準拠しています。この著作権と関係する組織によってカバーされる年に言及することをお勧めします( RECOMMENDED )。
/**
* @copyright 1997-2005 The PHP Group
*/
@deprecatedタグは、どの「構造的要素」が廃止され、将来のバージョンで削除されるかを示すために使用されます。
註）これは「非推奨」になった関数、クラス、メソッド、プロパティ―などを意味します。
@deprecated [<"Semantic Version">] [<description>]
@deprecated タグは、関連する「構造的要素」が廃止されたか、その使用が推奨されていないため、将来のバージョンで削除されることを宣言し、“Semantic Version” が提供されている場合はそれが有効です。
原文
The @deprecated tag declares that the associated 'Structural elements' will be removed in a future version as it has become obsolete or its usage is otherwise not recommended, effective from the “Semantic Version” if provided.
このタグは、関連する要素が廃止された理由を説明する追加の説明を提供する場合があります( MAY )。
関連付けられている要素が別の要素に取って代わられた場合は、同じ 'PHPDoc' に新しい要素を指す @see タグを追加することをお勧めします( RECOMMENDED )。
/**
* @deprecated
*
* @deprecated 1.0.0
*
* @deprecated No longer used by internal code and not recommended.
*
* @deprecated 1.0.0 No longer used by internal code and not recommended.
*/
@internal タグは、関連する「構造的要素」がこのアプリケーションまたはライブラリの内部の構造であることを示すために使用されます。説明の中で使用して、このソフトウェアの開発者にのみ適用されるテキストを挿入することもできます。
@internal [description]
またはインラインで：
{@internal [description]}
他のインラインタグとは異なり、このタグのインラインバージョンには他のインラインタグが含まれている場合があります（以下の2番目の例を参照）。
@internal タグは、関連付けられている「構造的要素」が、それが属するアプリケーション、ライブラリ、またはパッケージ内での使用のみを目的としていることを示しています。
作成者は、このタグを使用して、パブリックな可視性を持つ要素をAPIから除外するように見なされるべきであることを示すことができます( MAY ) - 例えば：
MAY )。MAY )。
PHPDoc コメントからドキュメントを生成する場合、ユーザーが内部要素を含めるべきであることを明示的に示さない限り、関連する要素を非表示にすることをお勧めします( RECOMMENDED )。
@internal の追加的用途は、内部コメントまたは追加の説明テキストをインラインで Description に追加することです。これは、例えば、このソフトウェアのソースコードからドキュメントを生成するときに、特定のビジネスクリティカルな情報、または混乱する情報を差し控えるために行われる場合があります。
カウント関数をこのプロジェクトの内部としてマークします：
/** * @internal * * @return int アイテムの数を示します。 */ function count() { <...> }
Description の中に開発者ドキュメントだけに表示されるメモに含めます。
/** * Fooの数を数えます。 * * このメソッドは、Fooの数を取得します。 * {@internal開発者は、黙って1つの余分なFooを追加することに注意すべきです * （{@link http://example.com}を参照）} * * @return int アイテムの数を示します。 */ function count() { <...> }
@link タグは、関連付けられた「構造的要素」と絶対的なURIで識別されるWebサイト間のカスタムな関係を示します。
@link タグを使用して、「構造的要素」、またはインラインで使用した場合は説明の一部とURIとの関係またはリンクを定義できます。
RFC 2396で指定されているように、URIは完全かつ整形式でなければなりません( MUST )。
@link タグには、この出現によって定義される関係のタイプを示す説明が追加されている場合があります( MAY )。
/** * @link http://example.com/my/bar Fooのドキュメント * * @return int アイテムの数を示します。 */ function count() { <...> } /** * このメソッドは、Fooの出現をカウントします。 * * Foo（{@link http://example.com/my/bar}）が与えられなくなると、常に1つのFooが存在する必要が * あるため、この関数は1つ追加します。 * * @return int アイテムの数を示します。 */ function count() { <...> }
@method により、クラスはどの「マジック」メソッドが呼び出し可能かを知ることができます。
@method [return type] [name]([type] [parameter], [...]) [description]
@method タグは、クラスが __call() マジックメソッドを含み、いくつかの明確な使用法を定義する状況で使用されます。
この例は、事前定義されたプロパティの動的ゲッターまたはセッターを持つ __call() を親に持つ子クラスです。子は存在する必要があるゲッターとセッターを知っていますが、__call() メソッドを使用して提供するために親クラスに依存しています。この状況では、子クラスには、各マジックセッターメソッドまたはゲッターメソッドごとに @method タグがあります。
@methodタグを使用すると、作成者は、シグニチャーにそれらの型を含めることで、引数と戻り値の型を伝達できます。
目的のメソッドに戻り値がない場合、戻り値の型は省略できます( MAY )。その場合、void が暗黙に示されます。
@method タグは、クラスまたはインターフェースに関連付けられている PHPDoc でのみ使用できます。
class Parent { public function __call() { <...> } } /** * @method setInteger(int $integer) * @method string getString() * @method void setString(int $integer) */ class Child extends Parent { <...> }
@package タグは、「構造的要素」を論理的な下位区分に分類するために使用されます。
@package [level 1]\[level 2]\[etc.]
@package タグは、名前空間の対応または補足として使用できます。名前空間は、「構造的要素」の機能的な下位区分を提供しますが、@package タグは、要素を異なる階層にグループ化できる論理的な下位区分を提供できます。
全体的に見て、論理的な区分と機能的な区分の両方が等しい場合、メンテナンスのオーバーヘッドを防ぐために @package タグを使用することは推奨されません( NOT RECOMMENDED )。
名前空間で知られているように、論理階層の各レベルをバックスラッシュ( \ )で区切る必要があります( MUST )。階層は無限の深さでもかまいませんが( MAY )、深さを6レベル以下に保つことをお勧めします( RECOMMENDED )。
パッケージは、その名前空間、クラス、またはインターフェースとそれらに含まれる要素に適用されます。つまり、@package タグを使い、ある名前空間に含まれる関数は、そのパッケージを想定していることになります。
このタグは、「DocBlock」内で複数回出現してはなりません( MUST NOT )。
/**
* @package PSR\Documentation\API
*/
@param タグは、関数またはメソッドの単一のパラメーターを文書化するために使用されます。
@param ["Type"] [name] [<description>]
@param タグを使用すると、関数またはメソッドの単一のパラメーターのタイプと機能を文書化できます。それが提供される場合、何が期待されるかを示す “Type” を含まなければなりません( MUST )。すべての有用な情報がコードシグニチャー自体に既に表示されているため、name はいくつかの @param タグが省略されている場合にのみ必要です。description はオプションですが( OPTIONAL )、推奨されています( RECOMMENDED )。
@param タグは複数行の説明を持つ場合があり( MAY )、明示的な区切りは必要ありません。
文書化する場合、すべての関数とメソッドでこのタグを使用することが推奨されます( RECOMMENDED )。
このタグは、「PHPDoc」内のパラメーターごとに複数回出現してはならず( MUST NOT )、メソッドまたは関数の「構造的要素」に限定されます。
/** * 指定された配列内のアイテムの数をカウントします。 * * @param mixed[] $items 要素をカウントする配列構造。 * * @return int 要素の数を返します。 */ function count(array $items) { <...> }
@property タグはどんな「マジック」プロパティがサポートされているのかを宣言するために使用されます。
@property[<-read|-write>] ["Type"] [name] [<description>]
@property タグは、クラス（またはトレイト）が __get() または __set() の「マジック」メソッドを実装して、実行時に非リテラルプロパティを解決するときに使用されます。
@property-read および @property-write バリアントは、読み取りまたは書き込みのみが可能な「マジック」プロパティを示すために使用される場合があります( MAY )。
@property タグは、クラスまたはトレイトに関連付けられているPHPDocでのみ使用できます。
次の例では、クラス User がマジックの__get()メソッドを実装して、「マジック」の読み取り専用の $full_name プロパティを実装しています：
/** * @property-read string $full_name */ class User { /** * @var string */ public $first_name; /** * @var string */ public $last_name; public function __get($name) { if ($name === "full_name") { return "{$this->first_name} {$this->last_name}"; } } }
@returnタグは、関数またはメソッドの戻り値を文書化するために使用されます。
@return <"Type"> [description]
@return タグを使用すると、関数またはメソッドの戻り値の型を文書化できます。指定する場合は、返されるものを示す「タイプ」を含める必要があります( MUST )。一方、連想配列などの複雑な戻り構造の場合、説明はオプションですが( OPTIONAL )、推奨されます( RECOMMENDED )。
@returnタグには複数行の説明が含まれる場合があり( MAY )、明示的な区切りは必要ありません。
すべての関数とメソッドでこのタグを使用することをお勧めします( RECOMMENDED )。この推奨事項の例外は（個々のプロジェクトのコーディング規約でも定義されている様に）、次のとおりです( MAY )：
戻り値のない関数とメソッド：@return タグはここでは省略できます( MAY )。その場合、インタプリタはこれを @return void が提供されているかのように解釈する必要があります( MUST )。
このタグは「DocBlock」内で2回以上出現してはならず( MUST NOT )、メソッドまたは関数の「構造的要素」の「DocBlock」に限定されます。
/** * @return int アイテムの数を示します。 */ function count() { <...> } /** * @return string|null ラベルのテキスト、または、提供されていない場合はnull。 */ function getLabel() { <...> }
@see タグは、関連する「構造的要素」からWebサイトまたはその他の「構造的要素」への参照を示します。
@see [URI | "FQSEN"] [<description>]
FQSEN：完全修飾要素名
@see タグを使用して、他の「構造的要素」またはURIへの参照を定義できます。
別の「構造的要素」への参照を定義する場合、二重コロンを追加してその要素の名前（「FQSEN」とも呼ばれる）を指定することにより、特定の要素を参照できます。
RFC 2396で指定されているように、URIは完全かつ整形式でなければなりません( MUST )。
@see タグは、要素とそのターゲットの間の関係に関する追加情報を提供する説明をすべきです( SHOULD )。さらに、@see タグには、この関係にさらに定義を追加するためのタグの特殊化が存在する場合があります( MAY )。
/** * @see number_of() :alias: （ ※特殊化の例 ） * @see MyClass::$items アイテムがカウントされるプロパティ。（ ※FQSENの例（プロパティ）） * @see MyClass::setItems() このコレクションのアイテムを設定します。（ ※FQSENの例（メソッド）） * @see http://example.com/my/bar Fooのドキュメント。（ ※URLの例 ） * * @return int アイテムの数を示します。 */ function count() { <...> }
@since タグは、要素の「バージョニング」の説明を使用して、要素がいつ導入または変更されたかを示すために使用されます。
@since [<"Semantic Version">] [<description>]
要素の導入または変更の「バージョン」を文書化します。
このバージョンは、セマンティックバージョン番号（x.x.x）と一致し、追加情報を提供するための説明を持っていること( MAY )が推奨されます( RECOMMENDED )。
この情報を使用して、特定の要素に対して必要なアプリケーションバージョンをコンシューマに通知する一連のAPIドキュメントを生成できます。
要素の現在のバージョンを表示するために @since タグを使用すべきではありません( SHOULD NOT )。@version タグを、その目的で使用できます( MAY )。
/** * これはFooです * @version 2.1.7 MyApp * @since 2.0.0 introduced */ class Foo { /** * barを作る。 * * @since 2.1.5 bar($arg1 = '', $arg2 = null) * $arg2オプションを導入 * @since 2.1.0 bar($arg1 = '') * $arg1オプションを導入 * @since 2.0.0 bar() * 新しくbar()メソッドを導入 */ public function bar($arg1 = '', $arg2 = null) { <...> } }
@throws タグは「構造的要素」が特定のタイプの Throwable（例外またはエラー）をスローするかどうかを示すために使用されます。
@throws ["Type"] [<description>]
@throws タグは「構造的要素」が特定のタイプのエラーをスローすることを示すために使用できます( MAY )。
このタグで提供されるタイプは、Throwable のサブタイプであるオブジェクトを表す必要があります( MUST )。
このタグは、ドキュメントの中で、どのエラーが発生し、どのような状況で発生するかを示すために使用されます。例外がスローされる理由の説明を提供することをお勧めします( RECOMMENDED )。
このタグは、たとえ同じタイプであっても、例外が発生するたびに提供することをお勧めします( RECOMMENDED )。すべての発生を文書化することにより、詳細なビューが作成され、コンシューマはどのエラーをチェックすれば良いかを知ることができます。
/** * 指定された配列内のアイテムの数をカウントします。 * * @param mixed[] $array 要素をカウントする配列構造。 * * @throws InvalidArgumentException 与えられた引数が'array'タイプではない場合。 * * @return int 要素の数を返します。 */ function count($items) { <...> }
@todo タグは、関連する「構造的要素」で開発アクティビティを実行する必要があるかどうかを示すために使用されます。
@todo [description]
@todo タグは、関連する「構造的要素」を取り巻くアクティビティが引き続き発生する必要があることを示すために使用されます。各タグには、原作者の意図を伝える説明を添付する必要があります( MUST )。ただし、これは問題番号を提供するのと同じくらい短い場合があります。
/** * 指定された配列内のアイテムの数をカウントします。 * * @todo カウントする配列パラメーターを追加する * * @return int 要素の数を返します。 */ function count() { <...> }
現在の「構造的要素」がターゲットとして提供されている「構造的要素」またはプロジェクトファイルを使用するかどうかを示します。
@uses [file | "FQSEN"] [<description>]
@uses タグは、関連する「構造的要素」の一部が別の「構造的要素」または現在のプロジェクトにあるファイルを使用するかどうかを示します。
別の「構造的要素」への参照を定義する場合、二重のコロンを追加し、その要素の名前（「FQSEN」とも呼ばれる）を指定することにより、特定の要素を参照できます。
このプロジェクトに含まれるファイルは、このタグで参照できます。これは、例えば、コントローラーと（ビューとしての）テンプレートファイルの間の関係を示すために使用できます。
このタグは、システム外の要素との関係を示すために使用してはならないため( MUST NOT )、URLは使用できません。外部要素との関係を示すには、@see タグを使用できます。
ジェネレータなど、このタグを使用するアプリケーションは、宛先要素に @used-by タグを提供することをお勧めします( RECOMMENDED )。これは、双方向のエクスペリエンスを提供し、静的分析を可能にするために使用できます。
/** * @uses \SimpleXMLElement::__construct() ※FQSENの例 */ function initializeXml() { <...> }
/** * @uses MyView.php ※ファイルの例 */ function executeMyView() { <...> }
@var タグを使用して、次の「構造的要素」の「タイプ」を文書化できます。
@var ["Type"] [element_name] [<description>]
@var タグは、定数、プロパティ、または変数の値によって表されるデータのタイプを定義します。
型が曖昧または不明である各定数またはプロパティ定義、または変数の前には、@var タグを含むDocBlockを付けるべきです( SHOULD )。他の変数の前にも、@varタグを含むDocBlockを付けることができます( MAY )。
@var タグには、ドキュメント化する要素の名前を含める必要があります( MUST )。これの例外は、プロパティ宣言が単一のプロパティのみを参照する場合です。この場合、プロパティの名前は省略できます( MAY )。
これは、複合ステートメントを使用して一連の定数またはプロパティを定義するときに使用されます。このような複合ステートメントは、複数のアイテムが表されている間、DocBlock を1つだけ持つことができます。
/** @var int $int これはカウンターです。 */ $int = 0; // ここには docblock があるべきではありません $int++;
Or:
または：
class Foo { /** @var string|null 説明を含める必要があります */ protected $description = null; public function setDescription($description) { // ここには docblock があるべきではありません $this->description = $description; } }
他の例としては、foreach 中の変数を明示的に文書化することです。多くの IDE はこの情報を使用して、オートコンプリートを支援します：
/** @var \Sqlite3 $sqlite */ foreach ($connections as $sqlite) { // ここには docblock があるべきではありません $sqlite->open('/my/database/path'); <...> }
複合ステートメントでも文書化できます：
class Foo { protected /** * @var string 説明を含める必要があります */ $name, /** * @var string 説明を含める必要があります */ $description; }
Or constants:
または定数の場合：
class Foo { const /** * @var string 説明を含める必要があります */ MY_CONST1 = "1", /** * @var string 説明を含める必要があります */ MY_CONST2 = "2"; }
@version タグは、要素に対する「バージョニング」の説明を示すために使用されます。
@version ["Semantic Version"] [<description>]
要素の現在の「バージョン」を文書化します。
この情報を使用して、特定のバージョンの要素についてコンシューマに通知するAPIドキュメントのセットを生成できます。
Semantic Versioning Standard version 2.0 で説明されているように、バージョン番号がセマンティックバージョン番号と一致することが推奨されます( RECOMMENDED )。
バージョン管理システムのバージョンベクトルもサポートされていますが、次の形式に従う必要があります( MUST )。
name-of-vcs: $vector$
バージョン固有の追加情報を伝える目的で、説明が提供される場合があります( MAY )。
@version タグは、要素の最終変更バージョンまたは導入バージョンを示すために使用することはできません( MAY NOT )。@sinceタグを、その目的で使用すべきです( SHOULD )。
/** * Fooクラスのファイル * @version 2.1.7 MyApp * (この文字列は、アプリケーションの全体的なバージョン番号を示します) * @version @package_version@ * (このPEAR置換キーワードは、パッケージのインストール時に拡張されます) ※バージョンベクターの例（PEAR） * @version $Id$ * (このCVSキーワードは、CVSファイルのリビジョン番号を表示するように展開されます) ※バージョンベクターの例（CVS） */ /** * これはFooです */ class Foo { <...> }