このページの2つのバージョン間の差分を表示します。
両方とも前のリビジョン 前のリビジョン 次のリビジョン | 前のリビジョン | ||
psr:psr19 [2020/09/16 12:48] tanaka [5.14. @throws] |
psr:psr19 [2020/09/17 11:43] (現在) y2sunlight |
||
---|---|---|---|
行 1: | 行 1: | ||
- | > 編集中 | ||
- | |||
====== PSR-19: PHPDoc tags(Draft) ====== | ====== PSR-19: PHPDoc tags(Draft) ====== | ||
行 550: | 行 548: | ||
==== 5.10. @property ===== | ==== 5.10. @property ===== | ||
- | The @property tag is used to declare which " | + | '' |
- | + | ||
- | '' | + | |
=== 構文 ==== | === 構文 ==== | ||
行 562: | 行 558: | ||
=== 説明 ==== | === 説明 ==== | ||
- | The @property tag is used when a class (or trait) implements the < | + | '' |
- | + | ||
- | '' | + | |
- | + | ||
- | The @property-read and @property-write variants MAY be used to indicate " | + | |
'' | '' | ||
- | |||
- | The @property tags can ONLY be used in a PHPDoc that is associated with a class or trait. | ||
'' | '' | ||
=== 例 ==== | === 例 ==== | ||
- | |||
- | In the following example, a class User implements the magic < | ||
次の例では、クラス '' | 次の例では、クラス '' | ||
行 608: | 行 596: | ||
==== 5.11. @return ===== | ==== 5.11. @return ===== | ||
- | |||
- | The @return tag is used to document the return value of functions or methods. | ||
@returnタグは、関数またはメソッドの戻り値を文書化するために使用されます。 | @returnタグは、関数またはメソッドの戻り値を文書化するために使用されます。 | ||
行 621: | 行 607: | ||
=== 説明 ==== | === 説明 ==== | ||
- | With the @return tag it is possible to document the return type of a function or method. When provided, it MUST contain a " | + | @return タグを使用すると、関数またはメソッドの戻り値の型を文書化できます。指定する場合は、返されるものを示す「タイプ」を含める必要があります( '' |
- | + | ||
- | @returnタグを使用すると、関数またはメソッドの戻り値の型を文書化できます。指定する場合は、返されるものを示す「タイプ」を含める必要があります( '' | + | |
- | + | ||
- | The @return tag MAY have a multi-line description and does not need explicit delimiting. | + | |
@returnタグには複数行の説明が含まれる場合があり( '' | @returnタグには複数行の説明が含まれる場合があり( '' | ||
- | |||
- | It is RECOMMENDED to use this tag with every function and method. An exception to this recommendation, | ||
すべての関数とメソッドでこのタグを使用することをお勧めします( '' | すべての関数とメソッドでこのタグを使用することをお勧めします( '' | ||
- | **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 タグはここでは省略できます( '' |
- | + | ||
- | **戻り値のない関数とメソッド**:@returnタグはここでは省略できます( '' | + | |
- | + | ||
- | This tag MUST NOT occur more than once in a " | + | |
このタグは「DocBlock」内で2回以上出現してはならず( '' | このタグは「DocBlock」内で2回以上出現してはならず( '' | ||
行 665: | 行 641: | ||
==== 5.12. @see ===== | ==== 5.12. @see ===== | ||
- | The @see tag indicates a reference from the associated " | + | @see タグは、関連する「構造的要素」からWebサイトまたはその他の「構造的要素」への参照を示します。 |
- | + | ||
- | @seeタグは、関連する「構造的要素」からWebサイトまたはその他の「構造的要素」への参照を示します。 | + | |
=== 構文 ==== | === 構文 ==== | ||
行 679: | 行 653: | ||
=== 説明 ==== | === 説明 ==== | ||
- | The @see tag can be used to define a reference to other " | + | @see タグを使用して、他の「構造的要素」またはURIへの参照を定義できます。 |
- | + | ||
- | @seeタグを使用して、他の「構造的要素」またはURIへの参照を定義できます。 | + | |
- | + | ||
- | When defining a reference to another " | + | |
別の「構造的要素」への参照を定義する場合、二重コロンを追加してその要素の名前(「FQSEN」とも呼ばれる)を指定することにより、特定の要素を参照できます。 | 別の「構造的要素」への参照を定義する場合、二重コロンを追加してその要素の名前(「FQSEN」とも呼ばれる)を指定することにより、特定の要素を参照できます。 | ||
- | |||
- | A URI MUST be complete and well-formed as specified in RFC 2396. | ||
[[https:// | [[https:// | ||
- | The @see tag SHOULD have a description to provide additional information regarding the relationship between the element and its target. Additionally, | + | @see タグは、要素とそのターゲットの間の関係に関する追加情報を提供する説明をすべきです( '' |
- | + | ||
- | @seeタグは、要素とそのターゲットの間の関係に関する追加情報を提供する説明をすべきです( '' | + | |
=== 例 ==== | === 例 ==== | ||
行 699: | 行 665: | ||
<code php> | <code php> | ||
/** | /** | ||
- | * @see number_of() : | + | * @see number_of() : |
- | * @see MyClass:: | + | * @see MyClass:: |
- | | + | * @see MyClass:: |
- | * @see MyClass:: | + | * @see http:// |
- | | + | |
- | * @see http:// | + | |
- | | + | |
* | * | ||
- | * @return int Indicates the number of items. | + | * @return int アイテムの数を示します。 |
- | | + | |
*/ | */ | ||
function count() | function count() | ||
行 720: | 行 682: | ||
==== 5.13. @since ===== | ==== 5.13. @since ===== | ||
- | The @since tag is used to denote when an element was introduced or modified, using some description of " | + | @since タグは、要素の「バージョニング」の説明を使用して、要素がいつ導入または変更されたかを示すために使用されます。 |
- | + | ||
- | @sinceタグは、要素の「バージョニング」の説明を使用して、要素がいつ導入または変更されたかを示すために使用されます。 | + | |
=== 構文 ==== | === 構文 ==== | ||
行 731: | 行 691: | ||
=== 説明 ==== | === 説明 ==== | ||
- | |||
- | Documents the " | ||
要素の導入または変更の「バージョン」を文書化します。 | 要素の導入または変更の「バージョン」を文書化します。 | ||
- | 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)と一致し、追加情報を提供するための説明を持っていること( '' |
- | + | ||
- | このバージョンは、セマンティックバージョン番号(x.x.x)と一致し、追加情報を提供するための説明が可能であること( '' | + | |
- | + | ||
- | 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ドキュメントを生成できます。 | この情報を使用して、特定の要素に対して必要なアプリケーションバージョンをコンシューマに通知する一連の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 タグを使用すべきではありません( '' |
- | + | ||
- | 要素の現在のバージョンを表示するために@sinceタグを使用すべきではありません( '' | + | |
=== 例 ==== | === 例 ==== | ||
行 779: | 行 731: | ||
==== 5.14. @throws ===== | ==== 5.14. @throws ===== | ||
- | The @throws tag is used to indicate whether " | + | @throws タグは「構造的要素」が特定のタイプの Throwable(例外またはエラー)をスローするかどうかを示すために使用されます。 |
- | + | ||
- | @throwsタグは、「構造的要素」が特定のタイプのThrowable(例外またはエラー)をスローするかどうかを示すために使用されます。 | + | |
=== 構文 ==== | === 構文 ==== | ||
行 791: | 行 741: | ||
=== 説明 ==== | === 説明 ==== | ||
- | The @throws tag MAY be used to indicate that " | + | @throws タグは「構造的要素」が特定のタイプのエラーをスローすることを示すために使用できます( '' |
- | + | ||
- | @throwsタグは、「構造的要素」が特定のタイプのエラーをスローすることを示すために使用される場合があります( '' | + | |
- | + | ||
- | The type provided with this tag MUST represent an object that is a subtype of Throwable. | + | |
- | このタグで提供されるタイプは、Throwableのサブタイプであるオブジェクトを表す必要があります( '' | + | このタグで提供されるタイプは、Throwable のサブタイプであるオブジェクトを表す必要があります( '' |
- | + | ||
- | 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. | + | |
このタグは、ドキュメントの中で、どのエラーが発生し、どのような状況で発生するかを示すために使用されます。例外がスローされる理由の説明を提供することをお勧めします( '' | このタグは、ドキュメントの中で、どのエラーが発生し、どのような状況で発生するかを示すために使用されます。例外がスローされる理由の説明を提供することをお勧めします( '' | ||
- | 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. | + | このタグは、たとえ同じタイプであっても、例外が発生するたびに提供することをお勧めします( '' |
- | + | ||
- | このタグは、たとえ同じタイプであっても、例外が発生するたびに提供することをお勧めします( '' | + | |
=== 例 ==== | === 例 ==== | ||
行 828: | 行 770: | ||
==== 5.15. @todo ===== | ==== 5.15. @todo ===== | ||
+ | |||
+ | @todo タグは、関連する「構造的要素」で開発アクティビティを実行する必要があるかどうかを示すために使用されます。 | ||
=== 構文 ==== | === 構文 ==== | ||
<code php> | <code php> | ||
+ | @todo [description] | ||
</ | </ | ||
=== 説明 ==== | === 説明 ==== | ||
+ | |||
+ | @todo タグは、関連する「構造的要素」を取り巻くアクティビティが引き続き発生する必要があることを示すために使用されます。各タグには、原作者の意図を伝える説明を添付する必要があります( '' | ||
=== 例 ==== | === 例 ==== | ||
<code php> | <code php> | ||
+ | /** | ||
+ | * 指定された配列内のアイテムの数をカウントします。 | ||
+ | * | ||
+ | * @todo カウントする配列パラメーターを追加する | ||
+ | * | ||
+ | * @return int 要素の数を返します。 | ||
+ | */ | ||
+ | function count() | ||
+ | { | ||
+ | <...> | ||
+ | } | ||
</ | </ | ||
行 844: | 行 802: | ||
==== 5.16. @uses ===== | ==== 5.16. @uses ===== | ||
+ | |||
+ | 現在の「構造的要素」がターゲットとして提供されている「構造的要素」またはプロジェクトファイルを使用するかどうかを示します。 | ||
=== 構文 ==== | === 構文 ==== | ||
<code php> | <code php> | ||
+ | @uses [file | " | ||
</ | </ | ||
=== 説明 ==== | === 説明 ==== | ||
+ | |||
+ | '' | ||
+ | |||
+ | 別の「構造的要素」への参照を定義する場合、二重のコロンを追加し、その要素の名前(「FQSEN」とも呼ばれる)を指定することにより、特定の要素を参照できます。 | ||
+ | |||
+ | このプロジェクトに含まれるファイルは、このタグで参照できます。これは、例えば、コントローラーと(ビューとしての)テンプレートファイルの間の関係を示すために使用できます。 | ||
+ | |||
+ | このタグは、システム外の要素との関係を示すために使用してはならないため( '' | ||
+ | |||
+ | ジェネレータなど、このタグを使用するアプリケーションは、宛先要素に '' | ||
=== 例 ==== | === 例 ==== | ||
<code php> | <code php> | ||
+ | /** | ||
+ | * @uses \SimpleXMLElement:: | ||
+ | */ | ||
+ | function initializeXml() | ||
+ | { | ||
+ | <...> | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | <code php> | ||
+ | /** | ||
+ | * @uses MyView.php ※ファイルの例 | ||
+ | */ | ||
+ | function executeMyView() | ||
+ | { | ||
+ | <...> | ||
+ | } | ||
</ | </ | ||
行 860: | 行 848: | ||
==== 5.17. @var ===== | ==== 5.17. @var ===== | ||
+ | |||
+ | @var タグを使用して、次の「構造的要素」の「タイプ」を文書化できます。 | ||
+ | |||
+ | * クラススコープ と グローバルスコープ の両方の定数 | ||
+ | * プロパティ | ||
+ | * 変数、グローバルスコープ と ローカルスコープ の両方 | ||
=== 構文 ==== | === 構文 ==== | ||
<code php> | <code php> | ||
+ | @var [" | ||
</ | </ | ||
=== 説明 ==== | === 説明 ==== | ||
+ | |||
+ | @var タグは、定数、プロパティ、または変数の値によって表されるデータのタイプを定義します。 | ||
+ | |||
+ | 型が曖昧または不明である各定数またはプロパティ定義、または変数の前には、@var タグを含むDocBlockを付けるべきです( '' | ||
+ | |||
+ | @var タグには、ドキュメント化する要素の名前を含める必要があります( '' | ||
+ | |||
+ | これは、複合ステートメントを使用して一連の定数またはプロパティを定義するときに使用されます。このような複合ステートメントは、複数のアイテムが表されている間、DocBlock を1つだけ持つことができます。 | ||
=== 例 ==== | === 例 ==== | ||
<code php> | <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 = " | ||
+ | |||
+ | } | ||
</ | </ | ||
行 876: | 行 951: | ||
==== 5.18. @version ===== | ==== 5.18. @version ===== | ||
+ | |||
+ | @version タグは、要素に対する「バージョニング」の説明を示すために使用されます。 | ||
=== 構文 ==== | === 構文 ==== | ||
<code php> | <code php> | ||
+ | @version [" | ||
</ | </ | ||
=== 説明 ==== | === 説明 ==== | ||
+ | |||
+ | 要素の現在の「バージョン」を文書化します。 | ||
+ | |||
+ | この情報を使用して、特定のバージョンの要素についてコンシューマに通知するAPIドキュメントのセットを生成できます。 | ||
+ | |||
+ | [[https:// | ||
+ | |||
+ | バージョン管理システムのバージョンベクトルもサポートされていますが、次の形式に従う必要があります( '' | ||
+ | |||
+ | < | ||
+ | name-of-vcs: | ||
+ | </ | ||
+ | |||
+ | バージョン固有の追加情報を伝える目的で、説明が提供される場合があります( '' | ||
+ | |||
+ | @version タグは、要素の最終変更バージョンまたは導入バージョンを示すために使用することはできません( '' | ||
=== 例 ==== | === 例 ==== | ||
<code php> | <code php> | ||
+ | /** | ||
+ | * Fooクラスのファイル | ||
+ | * @version 2.1.7 MyApp | ||
+ | | ||
+ | * @version @package_version@ | ||
+ | | ||
+ | * @version $Id$ | ||
+ | | ||
+ | */ | ||
+ | |||
+ | /** | ||
+ | * これはFooです | ||
+ | */ | ||
+ | class Foo | ||
+ | { | ||
+ | <...> | ||
+ | } | ||
</ | </ | ||