このページの2つのバージョン間の差分を表示します。
両方とも前のリビジョン 前のリビジョン 次のリビジョン | 前のリビジョン | ||
psr:psr19 [2020/09/01 11:57] tanaka [PSR-19: PHPDocタグ] |
psr:psr19 [2020/09/17 11:43] (現在) y2sunlight |
||
---|---|---|---|
行 1: | 行 1: | ||
- | > 編集中 | ||
- | |||
====== PSR-19: PHPDoc tags(Draft) ====== | ====== PSR-19: PHPDoc tags(Draft) ====== | ||
行 31: | 行 29: | ||
--- // 原文より翻訳 [[https:// | --- // 原文より翻訳 [[https:// | ||
+ | |||
+ | ===== 1. はじめに ====== | ||
+ | |||
+ | このPSRの主な目的は、[[https:// | ||
+ | |||
+ | * このドキュメントは、アノテーションのカタログを記述してはなりません( '' | ||
+ | * このドキュメントは、PHPDoc規約のアプリケーションに関するコーディング規約のベストプラクティスまたは推奨事項を説明しません( '' | ||
\\ | \\ | ||
+ | |||
+ | ===== 2. このドキュメントで使用される規則 ====== | ||
+ | |||
+ | このドキュメントのキーワード '' | ||
+ | |||
+ | > **RFC 2119の説明** | ||
+ | > '' | ||
+ | > '' | ||
+ | > '' | ||
+ | > '' | ||
+ | > '' | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ===== 3. 定義 ====== | ||
+ | |||
+ | [[https:// | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ===== 4. 継承について ====== | ||
+ | |||
+ | 「構造的要素」を実装、拡張、またはオーバーライドする「構造的要素」に関連付けられた PHPDoc には、実装、拡張、またはオーバーライドされた「構造的要素」に関連付けられた PHPDoc から情報の一部を継承する機能があります。 | ||
+ | |||
+ | 「構造的要素」のすべてのタイプのための PHPDoc は、次の部分が存在しない場合、その部分を継承する必要があります( '' | ||
+ | |||
+ | * [[https:// | ||
+ | * [[https:// | ||
+ | * [[https:// | ||
+ | * [[# | ||
+ | * [[# | ||
+ | * [[# | ||
+ | |||
+ | 「構造的要素」の各タイプのための PHPDoc は、関連付けられている「構造的要素」に応じて、タグの特殊なサブセットも継承する必要があります( '' | ||
+ | |||
+ | PHPDoc が Summary や Description などの部分を備えておらず、スーパー要素の PHPDoc に存在する場合、その部分は常に暗黙的に継承されます。以下は、DocBlock がスーパー要素の DocBlock から情報を継承できるすべての要素のリストです: | ||
+ | |||
+ | - クラスまたはインターフェイスの DocBlock は、拡張するクラスまたはインターフェースから情報を継承できます。 | ||
+ | - プロパティの DocBlock は、スーパークラスで宣言されている同じ名前のプロパティから情報を継承できます。 | ||
+ | - メソッドの DocBlock は、スーパークラスで宣言されている同じ名前のメソッドから情報を継承できます。 | ||
+ | - メソッドの DocBlock は、現在のクラスの実装済みインターフェースで宣言されている、またはスーパークラスで実装されている同じ名前のメソッドから情報を継承できます。 | ||
+ | |||
+ | > | ||
+ | > | ||
+ | > | ||
+ | > | ||
+ | > | ||
+ | |||
+ | 継承は、クラス階層グラフのルートからそのリーフまで行われます。これは、ツリーの下部で継承されたものは、オーバーライドされない限り、上部まで「バブル」する必要がある( '' | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== 4.1. @inheritDocタグを使用して継承を明示的にする ===== | ||
+ | |||
+ | 継承は暗黙的であるため、「構造的要素」に PHPDoc を含める必要がない場合があります。PHPDoc が故意に省略されたかどうか、またはコードの作成者がドキュメントを追加するのを忘れたかどうかが曖昧になるため、これにより混乱が生じる可能性があります。 | ||
+ | |||
+ | この曖昧さを解決するために、'' | ||
+ | |||
+ | 例: | ||
+ | |||
+ | <code php> | ||
+ | /** | ||
+ | * This is a summary. | ||
+ | */ | ||
+ | class SuperClass | ||
+ | { | ||
+ | } | ||
+ | |||
+ | /** | ||
+ | * @inheritDoc | ||
+ | */ | ||
+ | class SubClass extends SuperClass | ||
+ | { | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | 上記の例では、SubClass の Summary は SuperClass 要素の Summary と等しいと見なすことができます。つまり、「This is a summary.」です。 | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== 4.2. {@inheritDoc}インラインタグを使用して説明を拡張する ===== | ||
+ | |||
+ | スーパー要素の Description を継承し、独自のテキストを追加して、「構造的要素」に固有の情報を提供したい場合があります。これは、'' | ||
+ | |||
+ | '' | ||
+ | |||
+ | 例: | ||
+ | |||
+ | <code php> | ||
+ | /** | ||
+ | * これは、この要素のSummaryです。 | ||
+ | * | ||
+ | * {@inheritDoc} | ||
+ | * | ||
+ | * さらに、この説明には、この要素に固有の詳細な情報を提供する詳細情報が含まれます。 | ||
+ | */ | ||
+ | </ | ||
+ | |||
+ | 上記の例では、この PHPDoc の Description は、'' | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== 4.3. 要素固有の継承パーツ ===== | ||
+ | |||
+ | === 4.3.1. クラスまたはインターフェース ==== | ||
+ | |||
+ | この章の最初で定義されているように、継承された説明とタグに加えて、クラスまたはインターフェースは次のタグを継承する必要があります( '' | ||
+ | |||
+ | * [[# | ||
+ | |||
+ | \\ | ||
+ | |||
+ | === 4.3.2. 関数またはメソッド ==== | ||
+ | |||
+ | この章の最初で定義されているように、継承された説明とタグに加えて、関数または、クラスまたはインターフェースのメソッドは、次のタグを継承する必要があります( '' | ||
+ | |||
+ | * [[# | ||
+ | * [[# | ||
+ | * [[# | ||
+ | |||
+ | \\ | ||
+ | |||
+ | === 4.3.3. 定数またはプロパティ ==== | ||
+ | |||
+ | この章の最初で定義されているように、継承された説明とタグに加えて、クラスの定数またはプロパティは次のタグを継承する必要があります( '' | ||
+ | |||
+ | * [[# | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ===== 5. タグ ====== | ||
+ | |||
+ | 説明で特に言及されていない限り、各「DocBlock」で各タグが0回以上発生する場合があります( '' | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== 5.1. @api ===== | ||
+ | |||
+ | @api タグは、「構造的要素」をパッケージの主要なパブリックAPIの一部として強調するために使用されます。 | ||
+ | |||
+ | === 構文 ==== | ||
+ | |||
+ | <code php> | ||
+ | @api | ||
+ | </ | ||
+ | |||
+ | |||
+ | === 説明 ==== | ||
+ | |||
+ | '' | ||
+ | |||
+ | 公開されている他の「構造的要素」は、生成されたドキュメントではそれほど目立たないように記載されている場合があります( '' | ||
+ | |||
+ | [[# | ||
+ | |||
+ | === 例 ==== | ||
+ | |||
+ | <code php> | ||
+ | class UserService | ||
+ | { | ||
+ | /** | ||
+ | * このメソッドは公開APIです。 | ||
+ | * | ||
+ | * @api | ||
+ | */ | ||
+ | public function getUser() | ||
+ | { | ||
+ | <...> | ||
+ | } | ||
+ | |||
+ | /** | ||
+ | * このメソッドは「パッケージスコープ」ですが、公開APIではありません | ||
+ | */ | ||
+ | public function callMefromAnotherClass() | ||
+ | { | ||
+ | <...> | ||
+ | } | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== 5.2. @author ===== | ||
+ | |||
+ | @author タグは、「構造的要素」の作成者を文書化するために使用されます。 | ||
+ | |||
+ | === 構文 ==== | ||
+ | |||
+ | <code php> | ||
+ | @author [name] [<email address> | ||
+ | </ | ||
+ | |||
+ | === 説明 ==== | ||
+ | |||
+ | @author タグを使用して、「構造的要素」を作成した人、または「構造的要素」に大幅な変更を加えた人を示すことができます。このタグには、電子メールアドレスも含まれている場合があります( '' | ||
+ | |||
+ | === 例 ==== | ||
+ | |||
+ | <code php> | ||
+ | /** | ||
+ | * @author My Name | ||
+ | * @author My Name < | ||
+ | */ | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== 5.3. @copyright ===== | ||
+ | |||
+ | @copyrightタグは、「構造的要素」の著作権情報を文書化するために使用されます。 | ||
+ | |||
+ | === 構文 ==== | ||
+ | |||
+ | <code php> | ||
+ | @copyright < | ||
+ | </ | ||
+ | |||
+ | === 説明 ==== | ||
+ | |||
+ | @copyright タグは、「構造的要素」の著作権者を定義します。このタグで示された著作権は、特に明記されていない限り、それが適用される「構造的要素」とすべての子要素に適用されます。 | ||
+ | |||
+ | 説明の形式は、個々のプロジェクトのコーディング規約に準拠しています。この著作権と関係する組織によってカバーされる年に言及することをお勧めします( '' | ||
+ | |||
+ | === 例 ==== | ||
+ | |||
+ | <code php> | ||
+ | /** | ||
+ | * @copyright 1997-2005 The PHP Group | ||
+ | */ | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== 5.4. @deprecated ===== | ||
+ | |||
+ | @deprecatedタグは、どの「構造的要素」が廃止され、将来のバージョンで削除されるかを示すために使用されます。 | ||
+ | |||
+ | > 註)これは「非推奨」になった関数、クラス、メソッド、プロパティ―などを意味します。 | ||
+ | |||
+ | === 構文 ==== | ||
+ | |||
+ | <code php> | ||
+ | @deprecated [<" | ||
+ | </ | ||
+ | |||
+ | === 説明 ==== | ||
+ | |||
+ | @deprecated タグは、関連する「構造的要素」が廃止されたか、その使用が推奨されていないため、将来のバージョンで削除されることを宣言し、" | ||
+ | |||
+ | >'' | ||
+ | >The @deprecated tag declares that the associated ' | ||
+ | |||
+ | このタグは、関連する要素が廃止された理由を説明する追加の説明を提供する場合があります( '' | ||
+ | |||
+ | 関連付けられている要素が別の要素に取って代わられた場合は、同じ ' | ||
+ | |||
+ | === 例 ==== | ||
+ | |||
+ | <code php> | ||
+ | /** | ||
+ | * @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 タグは、関連する「構造的要素」がこのアプリケーションまたはライブラリの内部の構造であることを示すために使用されます。説明の中で使用して、このソフトウェアの開発者にのみ適用されるテキストを挿入することもできます。 | ||
+ | |||
+ | === 構文 ==== | ||
+ | |||
+ | <code php> | ||
+ | @internal [description] | ||
+ | </ | ||
+ | |||
+ | またはインラインで: | ||
+ | |||
+ | <code php> | ||
+ | {@internal [description]} | ||
+ | </ | ||
+ | |||
+ | 他のインラインタグとは異なり、このタグのインラインバージョンには他のインラインタグが含まれている場合があります(以下の2番目の例を参照)。 | ||
+ | |||
+ | === 説明 ==== | ||
+ | |||
+ | @internal タグは、関連付けられている「構造的要素」が、それが属するアプリケーション、ライブラリ、またはパッケージ内での使用のみを目的としていることを示しています。 | ||
+ | |||
+ | 作成者は、このタグを使用して、パブリックな可視性を持つ要素をAPIから除外するように見なされるべきであることを示すことができます( '' | ||
+ | |||
+ | * ライブラリの作成者は、内部要素への重大な変更をセマンティックバージョニングの対象外と見なしてもよい( '' | ||
+ | * 静的分析ツールは、他のライブラリ/ | ||
+ | |||
+ | PHPDoc コメントからドキュメントを生成する場合、ユーザーが内部要素を含めるべきであることを明示的に示さない限り、関連する要素を非表示にすることをお勧めします( '' | ||
+ | |||
+ | @internal の追加的用途は、内部コメントまたは追加の説明テキストをインラインで Description に追加することです。これは、例えば、このソフトウェアのソースコードからドキュメントを生成するときに、特定のビジネスクリティカルな情報、または混乱する情報を差し控えるために行われる場合があります。 | ||
+ | |||
+ | === 例 ==== | ||
+ | |||
+ | カウント関数をこのプロジェクトの内部としてマークします: | ||
+ | |||
+ | <code php> | ||
+ | /** | ||
+ | * @internal | ||
+ | * | ||
+ | * @return int アイテムの数を示します。 | ||
+ | */ | ||
+ | function count() | ||
+ | { | ||
+ | <...> | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | Description の中に開発者ドキュメントだけに表示されるメモに含めます。 | ||
+ | |||
+ | <code php> | ||
+ | /** | ||
+ | * Fooの数を数えます。 | ||
+ | * | ||
+ | * このメソッドは、Fooの数を取得します。 | ||
+ | * {@internal開発者は、黙って1つの余分なFooを追加することに注意すべきです | ||
+ | | ||
+ | * | ||
+ | * @return int アイテムの数を示します。 | ||
+ | */ | ||
+ | function count() | ||
+ | { | ||
+ | <...> | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== 5.6. @link ===== | ||
+ | |||
+ | @link タグは、関連付けられた「構造的要素」と絶対的なURIで識別されるWebサイト間のカスタムな関係を示します。 | ||
+ | |||
+ | === 構文 ==== | ||
+ | |||
+ | <code php> | ||
+ | @link [URI] [description] | ||
+ | </ | ||
+ | |||
+ | またはインラインで: | ||
+ | |||
+ | <code php> | ||
+ | {@link [URI] [description]} | ||
+ | </ | ||
+ | |||
+ | === 説明 ==== | ||
+ | |||
+ | @link タグを使用して、「構造的要素」、またはインラインで使用した場合は説明の一部とURIとの関係またはリンクを定義できます。 | ||
+ | |||
+ | [[https:// | ||
+ | |||
+ | @link タグには、この出現によって定義される関係のタイプを示す説明が追加されている場合があります( '' | ||
+ | |||
+ | === 例 ==== | ||
+ | |||
+ | <code php> | ||
+ | /** | ||
+ | * @link http:// | ||
+ | * | ||
+ | * @return int アイテムの数を示します。 | ||
+ | */ | ||
+ | function count() | ||
+ | { | ||
+ | <...> | ||
+ | } | ||
+ | |||
+ | /** | ||
+ | * このメソッドは、Fooの出現をカウントします。 | ||
+ | * | ||
+ | * Foo({@link http:// | ||
+ | * あるため、この関数は1つ追加します。 | ||
+ | * | ||
+ | * @return int アイテムの数を示します。 | ||
+ | */ | ||
+ | function count() | ||
+ | { | ||
+ | <...> | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== 5.7. @method ===== | ||
+ | |||
+ | @method により、クラスはどの「マジック」メソッドが呼び出し可能かを知ることができます。 | ||
+ | |||
+ | === 構文 ==== | ||
+ | |||
+ | <code php> | ||
+ | @method [return type] [name]([type] [parameter], | ||
+ | </ | ||
+ | |||
+ | === 説明 ==== | ||
+ | |||
+ | @method タグは、クラスが ''< | ||
+ | |||
+ | この例は、事前定義されたプロパティの動的ゲッターまたはセッターを持つ ''< | ||
+ | |||
+ | @methodタグを使用すると、作成者は、シグニチャーにそれらの型を含めることで、引数と戻り値の型を伝達できます。 | ||
+ | |||
+ | 目的のメソッドに戻り値がない場合、戻り値の型は省略できます( '' | ||
+ | |||
+ | @method タグは、クラスまたはインターフェースに関連付けられている PHPDoc でのみ使用できます。 | ||
+ | |||
+ | === 例 ==== | ||
+ | |||
+ | <code php> | ||
+ | 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 タグは、「構造的要素」を論理的な下位区分に分類するために使用されます。 | ||
+ | |||
+ | === 構文 ==== | ||
+ | |||
+ | <code php> | ||
+ | @package [level 1]\[level 2]\[etc.] | ||
+ | </ | ||
+ | |||
+ | === 説明 ==== | ||
+ | |||
+ | @package タグは、名前空間の対応または補足として使用できます。名前空間は、「構造的要素」の機能的な下位区分を提供しますが、@package タグは、要素を異なる階層にグループ化できる論理的な下位区分を提供できます。 | ||
+ | |||
+ | 全体的に見て、論理的な区分と機能的な区分の両方が等しい場合、メンテナンスのオーバーヘッドを防ぐために @package タグを使用することは推奨されません( '' | ||
+ | |||
+ | 名前空間で知られているように、論理階層の各レベルをバックスラッシュ( '' | ||
+ | |||
+ | パッケージは、その名前空間、クラス、またはインターフェースとそれらに含まれる要素に適用されます。つまり、@package タグを使い、ある名前空間に含まれる関数は、そのパッケージを想定していることになります。 | ||
+ | |||
+ | このタグは、「DocBlock」内で複数回出現してはなりません( '' | ||
+ | |||
+ | === 例 ==== | ||
+ | |||
+ | <code php> | ||
+ | /** | ||
+ | * @package PSR\Documentation\API | ||
+ | */ | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== 5.9. @param ===== | ||
+ | |||
+ | @param タグは、関数またはメソッドの単一のパラメーターを文書化するために使用されます。 | ||
+ | |||
+ | === 構文 ==== | ||
+ | |||
+ | <code php> | ||
+ | @param [" | ||
+ | </ | ||
+ | |||
+ | === 説明 ==== | ||
+ | |||
+ | @param タグを使用すると、関数またはメソッドの単一のパラメーターのタイプと機能を文書化できます。それが提供される場合、何が期待されるかを示す ''" | ||
+ | |||
+ | @param タグは複数行の説明を持つ場合があり( '' | ||
+ | |||
+ | 文書化する場合、すべての関数とメソッドでこのタグを使用することが推奨されます( '' | ||
+ | |||
+ | このタグは、「PHPDoc」内のパラメーターごとに複数回出現してはならず( '' | ||
+ | |||
+ | === 例 ==== | ||
+ | |||
+ | <code php> | ||
+ | /** | ||
+ | * 指定された配列内のアイテムの数をカウントします。 | ||
+ | * | ||
+ | * @param mixed[] $items 要素をカウントする配列構造。 | ||
+ | * | ||
+ | * @return int 要素の数を返します。 | ||
+ | */ | ||
+ | function count(array $items) | ||
+ | { | ||
+ | <...> | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== 5.10. @property ===== | ||
+ | |||
+ | '' | ||
+ | |||
+ | === 構文 ==== | ||
+ | |||
+ | <code php> | ||
+ | @property[< | ||
+ | </ | ||
+ | |||
+ | === 説明 ==== | ||
+ | |||
+ | '' | ||
+ | |||
+ | '' | ||
+ | |||
+ | '' | ||
+ | |||
+ | === 例 ==== | ||
+ | |||
+ | 次の例では、クラス '' | ||
+ | |||
+ | <code php> | ||
+ | /** | ||
+ | * @property-read string $full_name | ||
+ | */ | ||
+ | class User | ||
+ | { | ||
+ | /** | ||
+ | * @var string | ||
+ | */ | ||
+ | public $first_name; | ||
+ | |||
+ | /** | ||
+ | * @var string | ||
+ | */ | ||
+ | public $last_name; | ||
+ | |||
+ | public function __get($name) | ||
+ | { | ||
+ | if ($name === " | ||
+ | return " | ||
+ | } | ||
+ | } | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== 5.11. @return ===== | ||
+ | |||
+ | @returnタグは、関数またはメソッドの戻り値を文書化するために使用されます。 | ||
+ | |||
+ | === 構文 ==== | ||
+ | |||
+ | <code php> | ||
+ | @return <" | ||
+ | </ | ||
+ | |||
+ | === 説明 ==== | ||
+ | |||
+ | @return タグを使用すると、関数またはメソッドの戻り値の型を文書化できます。指定する場合は、返されるものを示す「タイプ」を含める必要があります( '' | ||
+ | |||
+ | @returnタグには複数行の説明が含まれる場合があり( '' | ||
+ | |||
+ | すべての関数とメソッドでこのタグを使用することをお勧めします( '' | ||
+ | |||
+ | **戻り値のない関数とメソッド**:@return タグはここでは省略できます( '' | ||
+ | |||
+ | このタグは「DocBlock」内で2回以上出現してはならず( '' | ||
+ | |||
+ | === 例 ==== | ||
+ | |||
+ | <code php> | ||
+ | /** | ||
+ | * @return int アイテムの数を示します。 | ||
+ | */ | ||
+ | function count() | ||
+ | { | ||
+ | <...> | ||
+ | } | ||
+ | |||
+ | /** | ||
+ | * @return string|null ラベルのテキスト、または、提供されていない場合はnull。 | ||
+ | */ | ||
+ | function getLabel() | ||
+ | { | ||
+ | <...> | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== 5.12. @see ===== | ||
+ | |||
+ | @see タグは、関連する「構造的要素」からWebサイトまたはその他の「構造的要素」への参照を示します。 | ||
+ | |||
+ | === 構文 ==== | ||
+ | |||
+ | <code php> | ||
+ | @see [URI | " | ||
+ | </ | ||
+ | |||
+ | > FQSEN:完全修飾要素名 | ||
+ | |||
+ | === 説明 ==== | ||
+ | |||
+ | @see タグを使用して、他の「構造的要素」またはURIへの参照を定義できます。 | ||
+ | |||
+ | 別の「構造的要素」への参照を定義する場合、二重コロンを追加してその要素の名前(「FQSEN」とも呼ばれる)を指定することにより、特定の要素を参照できます。 | ||
+ | |||
+ | [[https:// | ||
+ | |||
+ | @see タグは、要素とそのターゲットの間の関係に関する追加情報を提供する説明をすべきです( '' | ||
+ | |||
+ | === 例 ==== | ||
+ | |||
+ | <code php> | ||
+ | /** | ||
+ | * @see number_of() : | ||
+ | * @see MyClass:: | ||
+ | * @see MyClass:: | ||
+ | * @see http:// | ||
+ | * | ||
+ | * @return int アイテムの数を示します。 | ||
+ | */ | ||
+ | function count() | ||
+ | { | ||
+ | <...> | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== 5.13. @since ===== | ||
+ | |||
+ | @since タグは、要素の「バージョニング」の説明を使用して、要素がいつ導入または変更されたかを示すために使用されます。 | ||
+ | |||
+ | === 構文 ==== | ||
+ | |||
+ | <code php> | ||
+ | @since [<" | ||
+ | </ | ||
+ | |||
+ | === 説明 ==== | ||
+ | |||
+ | 要素の導入または変更の「バージョン」を文書化します。 | ||
+ | |||
+ | このバージョンは、セマンティックバージョン番号(x.x.x)と一致し、追加情報を提供するための説明を持っていること( '' | ||
+ | |||
+ | この情報を使用して、特定の要素に対して必要なアプリケーションバージョンをコンシューマに通知する一連のAPIドキュメントを生成できます。 | ||
+ | |||
+ | 要素の現在のバージョンを表示するために @since タグを使用すべきではありません( '' | ||
+ | |||
+ | === 例 ==== | ||
+ | |||
+ | <code php> | ||
+ | /** | ||
+ | * これはFooです | ||
+ | * @version 2.1.7 MyApp | ||
+ | * @since 2.0.0 introduced | ||
+ | */ | ||
+ | class Foo | ||
+ | { | ||
+ | /** | ||
+ | * barを作る。 | ||
+ | * | ||
+ | * @since 2.1.5 bar($arg1 = '', | ||
+ | | ||
+ | * @since 2.1.0 bar($arg1 = '' | ||
+ | | ||
+ | * @since 2.0.0 bar() | ||
+ | | ||
+ | */ | ||
+ | public function bar($arg1 = '', | ||
+ | { | ||
+ | <...> | ||
+ | } | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== 5.14. @throws ===== | ||
+ | |||
+ | @throws タグは「構造的要素」が特定のタイプの Throwable(例外またはエラー)をスローするかどうかを示すために使用されます。 | ||
+ | |||
+ | === 構文 ==== | ||
+ | |||
+ | <code php> | ||
+ | @throws [" | ||
+ | </ | ||
+ | |||
+ | === 説明 ==== | ||
+ | |||
+ | @throws タグは「構造的要素」が特定のタイプのエラーをスローすることを示すために使用できます( '' | ||
+ | |||
+ | このタグで提供されるタイプは、Throwable のサブタイプであるオブジェクトを表す必要があります( '' | ||
+ | |||
+ | このタグは、ドキュメントの中で、どのエラーが発生し、どのような状況で発生するかを示すために使用されます。例外がスローされる理由の説明を提供することをお勧めします( '' | ||
+ | |||
+ | このタグは、たとえ同じタイプであっても、例外が発生するたびに提供することをお勧めします( '' | ||
+ | |||
+ | === 例 ==== | ||
+ | |||
+ | <code php> | ||
+ | /** | ||
+ | * 指定された配列内のアイテムの数をカウントします。 | ||
+ | * | ||
+ | * @param mixed[] $array 要素をカウントする配列構造。 | ||
+ | * | ||
+ | * @throws InvalidArgumentException 与えられた引数が' | ||
+ | * | ||
+ | * @return int 要素の数を返します。 | ||
+ | */ | ||
+ | function count($items) | ||
+ | { | ||
+ | <...> | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== 5.15. @todo ===== | ||
+ | |||
+ | @todo タグは、関連する「構造的要素」で開発アクティビティを実行する必要があるかどうかを示すために使用されます。 | ||
+ | |||
+ | === 構文 ==== | ||
+ | |||
+ | <code php> | ||
+ | @todo [description] | ||
+ | </ | ||
+ | |||
+ | === 説明 ==== | ||
+ | |||
+ | @todo タグは、関連する「構造的要素」を取り巻くアクティビティが引き続き発生する必要があることを示すために使用されます。各タグには、原作者の意図を伝える説明を添付する必要があります( '' | ||
+ | |||
+ | === 例 ==== | ||
+ | |||
+ | <code php> | ||
+ | /** | ||
+ | * 指定された配列内のアイテムの数をカウントします。 | ||
+ | * | ||
+ | * @todo カウントする配列パラメーターを追加する | ||
+ | * | ||
+ | * @return int 要素の数を返します。 | ||
+ | */ | ||
+ | function count() | ||
+ | { | ||
+ | <...> | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== 5.16. @uses ===== | ||
+ | |||
+ | 現在の「構造的要素」がターゲットとして提供されている「構造的要素」またはプロジェクトファイルを使用するかどうかを示します。 | ||
+ | |||
+ | === 構文 ==== | ||
+ | |||
+ | <code php> | ||
+ | @uses [file | " | ||
+ | </ | ||
+ | |||
+ | === 説明 ==== | ||
+ | |||
+ | '' | ||
+ | |||
+ | 別の「構造的要素」への参照を定義する場合、二重のコロンを追加し、その要素の名前(「FQSEN」とも呼ばれる)を指定することにより、特定の要素を参照できます。 | ||
+ | |||
+ | このプロジェクトに含まれるファイルは、このタグで参照できます。これは、例えば、コントローラーと(ビューとしての)テンプレートファイルの間の関係を示すために使用できます。 | ||
+ | |||
+ | このタグは、システム外の要素との関係を示すために使用してはならないため( '' | ||
+ | |||
+ | ジェネレータなど、このタグを使用するアプリケーションは、宛先要素に '' | ||
+ | |||
+ | === 例 ==== | ||
+ | |||
+ | <code php> | ||
+ | /** | ||
+ | * @uses \SimpleXMLElement:: | ||
+ | */ | ||
+ | function initializeXml() | ||
+ | { | ||
+ | <...> | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | <code php> | ||
+ | /** | ||
+ | * @uses MyView.php ※ファイルの例 | ||
+ | */ | ||
+ | function executeMyView() | ||
+ | { | ||
+ | <...> | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== 5.17. @var ===== | ||
+ | |||
+ | @var タグを使用して、次の「構造的要素」の「タイプ」を文書化できます。 | ||
+ | |||
+ | * クラススコープ と グローバルスコープ の両方の定数 | ||
+ | * プロパティ | ||
+ | * 変数、グローバルスコープ と ローカルスコープ の両方 | ||
+ | |||
+ | === 構文 ==== | ||
+ | |||
+ | <code php> | ||
+ | @var [" | ||
+ | </ | ||
+ | |||
+ | === 説明 ==== | ||
+ | |||
+ | @var タグは、定数、プロパティ、または変数の値によって表されるデータのタイプを定義します。 | ||
+ | |||
+ | 型が曖昧または不明である各定数またはプロパティ定義、または変数の前には、@var タグを含むDocBlockを付けるべきです( '' | ||
+ | |||
+ | @var タグには、ドキュメント化する要素の名前を含める必要があります( '' | ||
+ | |||
+ | これは、複合ステートメントを使用して一連の定数またはプロパティを定義するときに使用されます。このような複合ステートメントは、複数のアイテムが表されている間、DocBlock を1つだけ持つことができます。 | ||
+ | |||
+ | === 例 ==== | ||
+ | |||
+ | <code php> | ||
+ | /** @var int $int これはカウンターです。 */ | ||
+ | $int = 0; | ||
+ | |||
+ | // ここには docblock があるべきではありません | ||
+ | $int++; | ||
+ | </ | ||
+ | |||
+ | Or: | ||
+ | |||
+ | または: | ||
+ | |||
+ | <code php> | ||
+ | class Foo | ||
+ | { | ||
+ | /** @var string|null 説明を含める必要があります */ | ||
+ | protected $description = null; | ||
+ | |||
+ | public function setDescription($description) | ||
+ | { | ||
+ | // ここには docblock があるべきではありません | ||
+ | $this-> | ||
+ | } | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | 他の例としては、foreach 中の変数を明示的に文書化することです。多くの IDE はこの情報を使用して、オートコンプリートを支援します: | ||
+ | |||
+ | <code php> | ||
+ | /** @var \Sqlite3 $sqlite */ | ||
+ | foreach ($connections as $sqlite) { | ||
+ | // ここには docblock があるべきではありません | ||
+ | $sqlite-> | ||
+ | <...> | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | 複合ステートメントでも文書化できます: | ||
+ | |||
+ | <code php> | ||
+ | class Foo | ||
+ | { | ||
+ | protected | ||
+ | /** | ||
+ | * @var string 説明を含める必要があります | ||
+ | */ | ||
+ | $name, | ||
+ | /** | ||
+ | * @var string 説明を含める必要があります | ||
+ | */ | ||
+ | $description; | ||
+ | |||
+ | } | ||
+ | </ | ||
+ | |||
+ | Or constants: | ||
+ | |||
+ | または定数の場合: | ||
+ | |||
+ | <code php> | ||
+ | class Foo | ||
+ | { | ||
+ | const | ||
+ | /** | ||
+ | * @var string 説明を含める必要があります | ||
+ | */ | ||
+ | MY_CONST1 = " | ||
+ | /** | ||
+ | * @var string 説明を含める必要があります | ||
+ | */ | ||
+ | MY_CONST2 = " | ||
+ | |||
+ | } | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== 5.18. @version ===== | ||
+ | |||
+ | @version タグは、要素に対する「バージョニング」の説明を示すために使用されます。 | ||
+ | |||
+ | === 構文 ==== | ||
+ | |||
+ | <code php> | ||
+ | @version [" | ||
+ | </ | ||
+ | |||
+ | === 説明 ==== | ||
+ | |||
+ | 要素の現在の「バージョン」を文書化します。 | ||
+ | |||
+ | この情報を使用して、特定のバージョンの要素についてコンシューマに通知するAPIドキュメントのセットを生成できます。 | ||
+ | |||
+ | [[https:// | ||
+ | |||
+ | バージョン管理システムのバージョンベクトルもサポートされていますが、次の形式に従う必要があります( '' | ||
+ | |||
+ | < | ||
+ | name-of-vcs: | ||
+ | </ | ||
+ | |||
+ | バージョン固有の追加情報を伝える目的で、説明が提供される場合があります( '' | ||
+ | |||
+ | @version タグは、要素の最終変更バージョンまたは導入バージョンを示すために使用することはできません( '' | ||
+ | |||
+ | === 例 ==== | ||
+ | |||
+ | <code php> | ||
+ | /** | ||
+ | * Fooクラスのファイル | ||
+ | * @version 2.1.7 MyApp | ||
+ | | ||
+ | * @version @package_version@ | ||
+ | | ||
+ | * @version $Id$ | ||
+ | | ||
+ | */ | ||
+ | |||
+ | /** | ||
+ | * これはFooです | ||
+ | */ | ||
+ | class Foo | ||
+ | { | ||
+ | <...> | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | |||
+ |