— y2sunlight 2020-07-28

本章は、若干の補足を加筆してはいるものの単にPSRのサイトを日本語に翻訳したものに過ぎません。英語が堪能な方は原文をご参照下さい。翻訳に当たっては、基本的に機械翻訳を使い、理解できない部分は独断で意訳しております。拙い訳では御座いますが恥を忍んで投稿しておりますので、ご指摘など御座いましたらコメントを頂ければ幸いです。

関連記事

• PSR - PHP標準勧告
• PSR-1: Basic Coding Standard - 基本コーディング規約
• PSR-3: Logger Interface - ロガーインターフェイス
• PSR-4: Autoloading Standard - オートローディング規約
• PSR-5: PHPDoc Standard(Draft) - PHPDoc規約
• PSR-6: Caching Interface - キャッシングインターフェイス
• PSR-7: HTTP Message Interface - HTTPメッセージインターフェイス
• PSR-11: Container Interface - コンテナインターフェイス
• PSR-12: Extended Coding Style - 拡張コーディングスタイル
• PSR-13: Link definition interfaces - リンク定義インターフェース
• PSR-14: Event Dispatcher - イベントディスパッチャー
• PSR-15: HTTP Server Request Handlers - HTTPサーバーリクエストハンドラー
• PSR-16: Common Interface for Caching Libraries - キャッシングライブラリのための共通インターフェース
• PSR-17: HTTP Factories - HTTPファクトリー
• PSR-18: HTTP Client - HTTPクライアント
• PSR-19: PHPDoc tags(Draft) - PHPDocタグ

— 原文より翻訳 PSR-19: PHPDoc tags 2020-09-01 現在

このPSRの主な目的は、PHPDoc規約でのタグの完全なカタログを提供することです。

• このドキュメントは、アノテーションのカタログを記述してはなりません( SHALL NOT )。
• このドキュメントは、PHPDoc規約のアプリケーションに関するコーディング規約のベストプラクティスまたは推奨事項を説明しません( 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 )：

• Summary
• Description そして
• タグの特定のサブセット：

  • @author
  • @copyright
  • @version

「構造的要素」の各タイプのための PHPDoc は、関連付けられている「構造的要素」に応じて、タグの特殊なサブセットも継承する必要があります( MUST )。

PHPDoc が Summary や Description などの部分を備えておらず、スーパー要素の PHPDoc に存在する場合、その部分は常に暗黙的に継承されます。以下は、DocBlock がスーパー要素の DocBlock から情報を継承できるすべての要素のリストです：

1. クラスまたはインターフェイスの DocBlock は、拡張するクラスまたはインターフェースから情報を継承できます。
2. プロパティの DocBlock は、スーパークラスで宣言されている同じ名前のプロパティから情報を継承できます。
3. メソッドの DocBlock は、スーパークラスで宣言されている同じ名前のメソッドから情報を継承できます。
4. メソッドの 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 )：

• @package

この章の最初で定義されているように、継承された説明とタグに加えて、関数または、クラスまたはインターフェースのメソッドは、次のタグを継承する必要があります( MUST )：

• @param
• @return
• @throws

この章の最初で定義されているように、継承された説明とタグに加えて、クラスの定数またはプロパティは次のタグを継承する必要があります( MUST )：

• @var

説明で特に言及されていない限り、各「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] [description]

またはインラインで：

{@link [URI] [description]}

@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)
{
    <...>
}

The @property tag is used to declare which “magic” properties are supported.

@property タグは、サポートされている「マジック」プロパティを宣言するために使用されます。

@property[<-read|-write>] ["Type"] [name] [<description>]

The @property tag is used when a class (or trait) implements the __get() and/or __set() “magic” methods to resolve non-literal properties at run-time.

@property タグは、クラス（またはトレイト）が __get() または __set() の「マジック」メソッドを実装して実行時に非リテラルプロパティを解決するときに使用されます。

The @property-read and @property-write variants MAY be used to indicate “magic” properties that can only be read or written.

@property-read および @property-write バリアントは、読み取りまたは書き込みのみが可能な「マジック」プロパティを示すために使用される場合があります( MAY )。

The @property tags can ONLY be used in a PHPDoc that is associated with a class or trait.

@property タグは、クラスまたはトレイトに関連付けられているPHPDocでのみ使用できます。

In the following example, a class User implements the magic __get() method, in order to implement a “magic”, read-only $full_name property:

次の例では、クラス 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}";
        }
    }
}

The @return tag is used to document the return value of functions or methods.

@returnタグは、関数またはメソッドの戻り値を文書化するために使用されます。

@return <"Type"> [description]

With the @return tag it is possible to document the return type of a function or method. When provided, it MUST contain a “Type” to indicate what is returned; the description on the other hand is OPTIONAL yet RECOMMENDED in case of complicated return structures, such as associative arrays.

@returnタグを使用すると、関数またはメソッドの戻り値の型を文書化できます。指定する場合は、返されるものを示す「タイプ」を含める必要があります( MUST )。一方、連想配列などの複雑な戻り構造の場合、説明はオプションですが( OPTIONAL )、推奨されます( RECOMMENDED )。

The @return tag MAY have a multi-line description and does not need explicit delimiting.

@returnタグには複数行の説明が含まれる場合があり( MAY )、明示的な区切りは必要ありません。

It is RECOMMENDED to use this tag with every function and method. An exception to this recommendation, as defined by the Coding Standard of any individual project, MAY be:

すべての関数とメソッドでこのタグを使用することをお勧めします( RECOMMENDED )。この推奨事項の例外は（個々のプロジェクトのコーディング規約でも定義されている様に）、次のとおりです( MAY )：

functions and methods without a return value: the @return tag MAY be omitted here, in which case an interpreter MUST interpret this as if @return void is provided.

戻り値のない関数とメソッド：@returnタグはここでは省略できます( MAY )。その場合、インタプリタはこれを @return void が提供されているかのように解釈する必要があります( MUST )。

This tag MUST NOT occur more than once in a “DocBlock” and is limited to the “DocBlock” of a “Structural Element” of a method or function.

このタグは「DocBlock」内で2回以上出現してはならず( MUST NOT )、メソッドまたは関数の「構造的要素」の「DocBlock」に限定されます。

/**
 * @return int アイテムの数を示します。
 */
function count()
{
    <...>
}
 
/**
 * @return string|null ラベルのテキスト、または、提供されていない場合はnull。
 */
function getLabel()
{
    <...>
}

The @see tag indicates a reference from the associated “Structural Elements” to a website or other “Structural Elements”.

@seeタグは、関連する「構造的要素」からWebサイトまたはその他の「構造的要素」への参照を示します。

@see [URI | "FQSEN"] [<description>]

FQSEN：完全修飾要素名

The @see tag can be used to define a reference to other “Structural Elements” or to a URI.

@seeタグを使用して、他の「構造的要素」またはURIへの参照を定義できます。

When defining a reference to another “Structural Elements” you can refer to a specific element by appending a double colon and providing the name of that element (also called the “FQSEN”).

別の「構造的要素」への参照を定義する場合、二重コロンを追加してその要素の名前（「FQSEN」とも呼ばれる）を指定することにより、特定の要素を参照できます。

A URI MUST be complete and well-formed as specified in RFC 2396.

RFC 2396で指定されているように、URIは完全かつ整形式でなければなりません( MUST )。

The @see tag SHOULD have a description to provide additional information regarding the relationship between the element and its target. Additionally, the @see tag MAY have a tag specialization to add further definition to this relationship.

@seeタグは、要素とそのターゲットの間の関係に関する追加情報を提供する説明をすべきです( SHOULD )。さらに、@seeタグには、この関係にさらに定義を追加するためのタグの特殊化がある場合があります( MAY )。

/**
 * @see number_of() :alias:       ※特殊化の例
 * @see MyClass::$items           For the property whose items are counted.
 *                                アイテムがカウントされるプロパティ。※FQSENの例（プロパティ）
 * @see MyClass::setItems()       To set the items for this collection.
 *                                このコレクションのアイテムを設定します。※FQSENの例（メソッド）
 * @see http://example.com/my/bar Documentation of Foo.
 *                                Fooのドキュメント。※URLの例
 *
 * @return int Indicates the number of items.
 *             アイテムの数を示します。
 */
function count()
{
    <...>
}

The @since tag is used to denote when an element was introduced or modified, using some description of “versioning” to that element.

@sinceタグは、要素の「バージョニング」の説明を使用して、要素がいつ導入または変更されたかを示すために使用されます。

@since [<"Semantic Version">] [<description>]

Documents the “version” of the introduction or modification of any element.

要素の導入または変更の「バージョン」を文書化します。

It is RECOMMENDED that the version matches a semantic version number (x.x.x) and MAY have a description to provide additional information.

このバージョンは、セマンティックバージョン番号（x.x.x）と一致し、追加情報を提供するための説明が可能であること( MAY )を推奨します( RECOMMENDED )。

This information can be used to generate a set of API Documentation where the consumer is informed which application version is necessary for a specific element.

この情報を使用して、特定の要素に対して必要なアプリケーションバージョンをコンシューマに通知する一連のAPIドキュメントを生成できます。

The @since tag SHOULD NOT be used to show the current version of an element, the @version tag MAY be used for that purpose.

要素の現在のバージョンを表示するために@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)
    {
        <...>
    }
}

The @throws tag is used to indicate whether “Structural Elements” throw a specific type of Throwable (exception or error).

@throwsタグは、「構造的要素」が特定のタイプのThrowable（例外またはエラー）をスローするかどうかを示すために使用されます。

@throws ["Type"] [<description>]

The @throws tag MAY be used to indicate that “Structural Elements” throw a specific type of error.

@throwsタグは、「構造的要素」が特定のタイプのエラーをスローすることを示すために使用される場合があります( MAY )。

The type provided with this tag MUST represent an object that is a subtype of Throwable.

このタグで提供されるタイプは、Throwableのサブタイプであるオブジェクトを表す必要があります( MUST )。

This tag is used to present in your documentation which error COULD occur and under which circumstances. It is RECOMMENDED to provide a description that describes the reason an exception is thrown.

このタグは、ドキュメントの中で、どのエラーが発生し、どのような状況で発生するかを示すために使用されます。例外がスローされる理由の説明を提供することをお勧めします( RECOMMENDED )。

It is also RECOMMENDED that this tag occurs for every occurrence of an exception, even if it has the same type. By documenting every occurrence a detailed view is created and the consumer knows for which errors to check.

このタグは、たとえ同じタイプであっても、例外が発生するたびに提供することをお勧めします( RECOMMENDED )。すべての発生を文書化することにより、詳細なビューが作成され、コンシューマはどのエラーをチェックするかを知ることができます。

/**
 * 指定された配列内のアイテムの数をカウントします。
 *
 * @param mixed[] $array 要素をカウントする配列構造。
 *
 * @throws InvalidArgumentException 与えられた引数が'array'タイプではない場合。
 *
 * @return int 要素の数を返します。
 */
function count($items)
{
    <...>
}