メインメニュー
XAMPP アレンジ
IED
WSL2
-
道具箱
リポジトリ編
フレームワーク編
公開ソフトウェア
メタ
リンク
- PHP ライブラリ
- PHP 言語
psr:psr19目次
文書の過去の版を表示しています。
編集中PSR-19: PHPDoc tags(Draft)
— y2sunlight 2020-07-28
本章は、若干の補足を加筆してはいるものの単にPSRのサイトを日本語に翻訳したものに過ぎません。英語が堪能な方は原文をご参照下さい。翻訳に当たっては、基本的に機械翻訳を使い、理解できない部分は独断で意訳しております。拙い訳では御座いますが恥を忍んで投稿しておりますので、ご指摘など御座いましたらコメントを頂ければ幸いです。
関連記事
- PSR-19: PHPDoc tags(Draft) - PHPDocタグ
PSR-19: PHPDocタグ(ドラフト)
— 原文より翻訳 PSR-19: PHPDoc tags 2020-09-01 現在
1. はじめに
このPSRの主な目的は、PHPDoc規約でのタグの完全なカタログを提供することです。
- このドキュメントは、アノテーションのカタログを記述してはなりません(
SHALL NOT
)。 - このドキュメントは、PHPDoc規約のアプリケーションに関するコーディング規約のベストプラクティスまたは推奨事項を説明しません(
SHALL NOT
)。このドキュメントは、構文と意図の正式な仕様に限定されています。
2. このドキュメントで使用される規則
このドキュメントのキーワード
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
— オプション
3. 定義
PHPDoc PSR(PSR-5)の定義セクション(
3.Definitions
) を参照してください。これらの定義もここで適用されます。
4. 継承について
「構造的要素」を実装、拡張、またはオーバーライドする「構造的要素」に関連付けられた PHPDoc には、実装、拡張、またはオーバーライドされた「構造的要素」に関連付けられた PHPDoc から情報の一部を継承する機能があります。
「構造的要素」のすべてのタイプのための PHPDoc は、次の部分が存在しない場合、その部分を継承する必要があります(
MUST
):- Description そして
- タグの特定のサブセット:
「構造的要素」の各タイプのための PHPDoc は、関連付けられている「構造的要素」に応じて、タグの特殊なサブセットも継承する必要があります(
MUST
)。PHPDoc が Summary や Description などの部分を備えておらず、スーパー要素の PHPDoc に存在する場合、その部分は常に暗黙的に継承されます。以下は、DocBlock がスーパー要素の DocBlock から情報を継承できるすべての要素のリストです:
- クラスまたはインターフェイスの DocBlock は、拡張するクラスまたはインターフェースから情報を継承できます。
- プロパティの DocBlock は、スーパークラスで宣言されている同じ名前のプロパティから情報を継承できます。
- メソッドの DocBlock は、スーパークラスで宣言されている同じ名前のメソッドから情報を継承できます。
- メソッドの DocBlock は、現在のクラスの実装済みインターフェースで宣言されている、またはスーパークラスで実装されている同じ名前のメソッドから情報を継承できます。
例えば:
メソッド\SubClass::myMethod()
があり、そのクラス\SubClass
がクラス\SuperClass
を拡張するとします。そしてクラス\SuperClass
には同じ名前のメソッドがあります(例:\SuperClass::myMethod
)。
上記が当てはまる場合、\SubClass::myMethod()
のDocBlockは、\SuperClass::myMethod
の PHPDoc から上記の部分を継承します。従って、@version
タグが再定義されなかった場合、\SubClass::myMethod()
がスーパー要素と同じ@version
タグを持つと想定されます。継承は、クラス階層グラフのルートからそのリーフまで行われます。これは、ツリーの下部で継承されたものは、オーバーライドされない限り、上部まで「バブル」する必要がある(
MUST
)ことを意味します。
4.1. @inheritDocタグを使用して継承を明示的にする
継承は暗黙的であるため、「構造的要素」に PHPDoc を含める必要がない場合があります。PHPDoc が故意に省略されたかどうか、またはコードの作成者がドキュメントを追加するのを忘れたかどうかが曖昧になるため、これにより混乱が生じる可能性があります。
この曖昧さを解決するために、
@inheritDoc
タグを使用して、この要素がスーパー要素から情報を継承することを示すことができます。例:
/** * This is a summary. */ class SuperClass { } /** * @inheritDoc */ class SubClass extends SuperClass { }
上記の例では、SubClass の Summary は SuperClass 要素の Summary と等しいと見なすことができます。つまり、「This is a summary.」です。
4.2. {@inheritDoc}インラインタグを使用して説明を拡張する
スーパー要素の Description を継承し、独自のテキストを追加して、「構造的要素」に固有の情報を提供したい場合があります。これは、
{@inheritDoc}
インラインタグを使用して行う必要があります(MUST
)。{@inheritDoc}
インラインタグは、その場所にスーパー要素の説明を挿入または推測する必要があることを示します(MUST
)。例:
/** * これは、この要素のSummaryです。 * * {@inheritDoc} * * さらに、この説明には、この要素に固有の詳細な情報を提供する詳細情報が含まれます。 */
上記の例では、この PHPDoc の Description は、
{@inheritDoc}
インラインタグで示されるスーパー要素の Description と、それに続く本文テキストの組み合わせであることを示しています。
4.3. 要素固有の継承パーツ
4.3.1. クラスまたはインターフェース
4.3.2. 関数またはメソッド
この章の最初で定義されているように、継承された説明とタグに加えて、関数または、クラスまたはインターフェースのメソッドは、次のタグを継承する必要があります(
MUST
):
4.3.3. 定数またはプロパティ
5. タグ
説明で特に言及されていない限り、各「DocBlock」で各タグが0回以上発生する場合があります(
MAY
)。
5.1. @api
@api タグは、「構造的要素」をパッケージの主要なパブリックAPIの一部として強調するために使用されます。
構文
@api
説明
@api
タグを公開されている「構造的要素」に適用して、生成されたドキュメントでそれらを強調し、ライブラリまたはフレームワークの主要な公開APIコンポーネントをコンシューマーに示すことができます(MAY
)。公開されている他の「構造的要素」は、生成されたドキュメントではそれほど目立たないように記載されている場合があります(
MAY
)。@internalも参照してください。これは、生成されたドキュメントから内部APIコンポーネントを非表示にするために使用できます(
MAY
)。例
class UserService { /** * このメソッドは公開APIです。 * * @api */ public function getUser() { <...> } /** * このメソッドは「パッケージスコープ」ですが、公開APIではありません */ public function callMefromAnotherClass() { <...> } }
5.2. @author
@author タグは、「構造的要素」の作成者を文書化するために使用されます。
構文
@author [name] [<email address>]
説明
@author タグを使用して、「構造的要素」を作成した人、または「構造的要素」に大幅な変更を加えた人を示すことができます。このタグには、電子メールアドレスも含まれている場合があります(
MAY
)。電子メールアドレスを指定する場合は、作成者名の後に山かっこ(<
>
)で囲む必要があり(MUST
)、RFC 2822 で定義されている構文に準拠する必要があります(MUST
)。例
/** * @author My Name * @author My Name <my.name@example.com> */
5.3. @copyright
@copyrightタグは、「構造的要素」の著作権情報を文書化するために使用されます。
構文
@copyright <description>
説明
@copyright タグは、「構造的要素」の著作権者を定義します。このタグで示された著作権は、特に明記されていない限り、それが適用される「構造的要素」とすべての子要素に適用されます。
説明の形式は、個々のプロジェクトのコーディング規約に準拠しています。この著作権と関係する組織によってカバーされる年に言及することをお勧めします(
RECOMMENDED
)。例
/** * @copyright 1997-2005 The PHP Group */
5.4. @deprecated
@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. */
5.5. @internal
@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() { <...> }
5.6. @link
@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() { <...> }
5.7. @method
@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 { <...> }
5.8. @package
@package タグは、「構造的要素」を論理的な下位区分に分類するために使用されます。
構文
@package [level 1]\[level 2]\[etc.]
説明
@package タグは、名前空間の対応または補足として使用できます。名前空間は、「構造的要素」の機能的な下位区分を提供しますが、@package タグは、要素を異なる階層にグループ化できる論理的な下位区分を提供できます。
全体的に見て、論理的な区分と機能的な区分の両方が等しい場合、メンテナンスのオーバーヘッドを防ぐために @package タグを使用することは推奨されません(
NOT RECOMMENDED
)。名前空間で知られているように、論理階層の各レベルをバックスラッシュ(
\
)で区切る必要があります(MUST
)。階層は無限の深さでもかまいませんが(MAY
)、深さを6レベル以下に保つことをお勧めします(RECOMMENDED
)。パッケージは、その名前空間、クラス、またはインターフェースとそれらに含まれる要素に適用されます。つまり、@package タグを使い、ある名前空間に含まれる関数は、そのパッケージを想定していることになります。
このタグは、「DocBlock」内で複数回出現してはなりません(
MUST NOT
)。例
/** * @package PSR\Documentation\API */
5.9. @param
@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) { <...> }
5.10. @property
@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}"; } } }
5.11. @return
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() { <...> }
5.12. @see
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() { <...> }
5.13. @since
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) { <...> } }
5.14. @throws
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) { <...> }
5.15. @todo
The @todo tag is used to indicate whether any development activities should still be executed on associated “Structural Elements”.
@todoタグは、関連する「構造的要素」で開発アクティビティを実行する必要があるかどうかを示すために使用されます。
構文
@todo [description]
説明
The @todo tag is used to indicate that an activity surrounding the associated “Structural Elements” must still occur. Each tag MUST be accompanied by a description that communicates the intent of the original author; this could however be as short as providing an issue number.
@todoタグは、関連する「構造的要素」を取り巻くアクティビティが引き続き発生する必要があることを示すために使用されます。各タグには、原作者の意図を伝える説明を添付する必要があります( MUST )。ただし、これは問題番号を提供するのと同じくらい短い場合があります。
例
/** * 指定された配列内のアイテムの数をカウントします。 * * @todo カウントする配列パラメーターを追加する * * @return int 要素の数を返します。 */ function count() { <...> }
5.16. @uses
Indicates whether the current “Structural Element” consumes the “Structural Element”, or project file, that is provided as target.
現在の「構造的要素」がターゲットとして提供されている「構造的要素」またはプロジェクトファイルを使用するかどうかを示します。
構文
@uses [file | "FQSEN"] [<description>]
説明
The @uses tag describes whether any part of the associated “Structural Element” uses, or consumes, another “Structural Element” or a file that is situated in the current project.
@uses
タグは、関連する「構造的要素」の一部が別の「構造的要素」または現在のプロジェクトにあるファイルを使用するかどうかを示します。When defining a reference to another “Structural Element” you can refer to a specific element by appending a double colon and providing the name of that element (also called the “FQSEN”).
別の「構造的要素」への参照を定義する場合、二重のコロンを追加し、その要素の名前(「FQSEN」とも呼ばれる)を指定することにより、特定の要素を参照できます。
Files that are contained in this project can be referred to by this tag. This can be used, for example, to indicate a relationship between a Controller and a template file (as View).
このプロジェクトに含まれるファイルは、このタグで参照できます。これは、例えば、コントローラーと(ビューとしての)テンプレートファイルの間の関係を示すために使用できます。
This tag MUST NOT be used to indicate relations to elements outside of the system, so URLs are not usable. To indicate relations with outside elements the @see tag can be used.
このタグは、システム外の要素との関係を示すために使用してはならないため(
MUST NOT
)、URLは使用できません。外部要素との関係を示すには、@seeタグを使用できます。Applications consuming this tag, such as generators, are RECOMMENDED to provide a @used-by tag on the destination element. This can be used to provide a bi-directional experience and allow for static analysis.
ジェネレータなど、このタグを使用するアプリケーションは、宛先要素に
@used-by
タグを提供することをお勧めします(RECOMMENDED
)。これは、双方向のエクスペリエンスを提供し、静的分析を可能にするために使用できます。例
/** * @uses \SimpleXMLElement::__construct() ※FQSENの例 */ function initializeXml() { <...> }
/** * @uses MyView.php ※ファイルの例 */ function executeMyView() { <...> }
5.17. @var
You may use the @var tag to document the “Type” of the following “Structural Elements”:
@varタグを使用して、次の「構造的要素」の「タイプ」を文書化できます。
- Constants, both class and global scope
- Properties
- Variables, both global and local scope
- クラススコープとグローバルスコープの両方の定数
- プロパティ
- 変数、グローバルスコープとローカルスコープの両方
構文
@var ["Type"] [element_name] [<description>]
説明
The @var tag defines which type of data is represented by a value of a Constant, Property or Variable.
@varタグは、定数、プロパティ、または変数の値によって表されるデータのタイプを定義します。
Each Constant or Property definition or Variable where the type is ambiguous or unknown SHOULD be preceded by a DocBlock containing the @var tag. Any other variable MAY be preceded with a DocBlock containing the @var tag.
型があいまいまたは不明である各定数またはプロパティ定義または変数の前には、@varタグを含むDocBlockを付けるべきです(
SHOULD
)。他の変数の前にも、@varタグを含むDocBlockを付けることができます(MAY
)。The @var tag MUST contain the name of the element it documents. An exception to this is when property declarations only refer to a single property. In this case the name of the property MAY be omitted.
@varタグには、ドキュメント化する要素の名前を含める必要があります(
MUST
)。これの例外は、プロパティ宣言が単一のプロパティのみを参照する場合です。この場合、プロパティの名前は省略できます(MAY
)。This is used when compound statements are used to define a series of Constants or Properties. Such a compound statement can only have one DocBlock while several items are represented.
これは、複合ステートメントを使用して一連の定数またはプロパティを定義するときに使用されます。このような複合ステートメントは、複数のアイテムが表されている間、DocBlockを1つだけ持つことができます。
例
/** @var int $intこれはカウンターです。 */ $int = 0; // there should be no docblock here // ここにはdocblockがあるべきではありません $int++;
Or:
または:
class Foo { /** @var string|null 説明を含める必要があります */ protected $description = null; public function setDescription($description) { // there should be no docblock here // ここにはdocblockがあるべきではありません $this->description = $description; } }
Another example is to document the variable in a foreach explicitly; many IDEs use this information to help you with auto-completion:
他の例としては、foreach中の変数を明示的に文書化することです。多くのIDEはこの情報を使用して、オートコンプリートを支援します:
/** @var \Sqlite3 $sqlite */ foreach ($connections as $sqlite) { // there should be no docblock here // ここにはdocblockがあるべきではありません $sqlite->open('/my/database/path'); <...> }
Even compound statements may be documented:
複合ステートメントでも文書化できます:
class Foo { protected /** * @var string 説明を含める必要があります */ $name, /** * @var string 説明を含める必要があります */ $description; }
Or constants:
または定数の場合:
class Foo { const /** * @var string 説明を含める必要があります */ MY_CONST1 = "1", /** * @var string 説明を含める必要があります */ MY_CONST2 = "2"; }
5.18. @version
The @version tag is used to denote some description of “versioning” to an element.
@versionタグは、要素に対する「バージョニング」の説明を示すために使用されます。
構文
@version ["Semantic Version"] [<description>]
説明
Documents the current “version” of any element.
要素の現在の「バージョン」を文書化します。
This information can be used to generate a set of API Documentation where the consumer is informed about elements at a particular version.
この情報を使用して、特定のバージョンの要素についてコンシューマに通知するAPIドキュメントのセットを生成できます。
It is RECOMMENDED that the version number matches a semantic version number as described in the Semantic Versioning Standard version 2.0.
Semantic Versioning Standard version 2.0で説明されているように、バージョン番号がセマンティックバージョン番号と一致することが推奨されます(
RECOMMENDED
)。Version vectors from Version Control Systems are also supported, though they MUST follow the form:
バージョン管理システムのバージョンベクターもサポートされていますが、次の形式に従う必要があります(
MUST
)。name-of-vcs: $vector$
A description MAY be provided, for the purpose of communicating any additional version-specific information.
バージョン固有の追加情報を伝える目的で、説明が提供される場合があります(
MAY
)。The @version tag MAY NOT be used to show the last modified or introduction version of an element, the @since tag SHOULD be used for that purpose.
@versionタグは、要素の最終変更バージョンまたは導入バージョンを示すために使用することはできません(
MAY NOT
)。@sinceタグを、その目的で使用すべきです(SHOULD
)。例
/** * Fooクラスのファイル * @version 2.1.7 MyApp * (この文字列は、アプリケーションの全体的なバージョン番号を示します) * @version @package_version@ * (このPEAR置換キーワードは、パッケージのインストール時に拡張されます) ※バージョンベクターの例(PEAR) * @version $Id$ * (このCVSキーワードは、CVSファイルのリビジョン番号を表示するように展開されます) ※バージョンベクターの例(CVS) */ /** * これはFooです */ class Foo { <...> }
psr/psr19.1600305720.txt.gz · 最終更新: 2020/09/17 10:22 by y2sunlight
コメント