このページの2つのバージョン間の差分を表示します。
両方とも前のリビジョン 前のリビジョン 次のリビジョン | 前のリビジョン 次のリビジョン 両方とも次のリビジョン | ||
psr:psr19 [2020/09/16 12:58] tanaka [5.17. @var] |
psr:psr19 [2020/09/17 11:41] y2sunlight [5.13. @since] |
||
---|---|---|---|
行 550: | 行 550: | ||
==== 5.10. @property ===== | ==== 5.10. @property ===== | ||
- | The @property tag is used to declare which " | + | '' |
- | + | ||
- | '' | + | |
=== 構文 ==== | === 構文 ==== | ||
行 562: | 行 560: | ||
=== 説明 ==== | === 説明 ==== | ||
- | 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: | 行 598: | ||
==== 5.11. @return ===== | ==== 5.11. @return ===== | ||
- | |||
- | The @return tag is used to document the return value of functions or methods. | ||
@returnタグは、関数またはメソッドの戻り値を文書化するために使用されます。 | @returnタグは、関数またはメソッドの戻り値を文書化するために使用されます。 | ||
行 621: | 行 609: | ||
=== 説明 ==== | === 説明 ==== | ||
- | 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: | 行 643: | ||
==== 5.12. @see ===== | ==== 5.12. @see ===== | ||
- | The @see tag indicates a reference from the associated " | + | @see タグは、関連する「構造的要素」からWebサイトまたはその他の「構造的要素」への参照を示します。 |
- | + | ||
- | @seeタグは、関連する「構造的要素」からWebサイトまたはその他の「構造的要素」への参照を示します。 | + | |
=== 構文 ==== | === 構文 ==== | ||
行 679: | 行 655: | ||
=== 説明 ==== | === 説明 ==== | ||
- | 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: | 行 667: | ||
<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: | 行 684: | ||
==== 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: | 行 693: | ||
=== 説明 ==== | === 説明 ==== | ||
- | |||
- | 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: | 行 733: | ||
==== 5.14. @throws ===== | ==== 5.14. @throws ===== | ||
- | The @throws tag is used to indicate whether " | + | @throws タグは「構造的要素」が特定のタイプの Throwable(例外またはエラー)をスローするかどうかを示すために使用されます。 |
- | + | ||
- | @throwsタグは、「構造的要素」が特定のタイプのThrowable(例外またはエラー)をスローするかどうかを示すために使用されます。 | + | |
=== 構文 ==== | === 構文 ==== | ||
行 791: | 行 743: | ||
=== 説明 ==== | === 説明 ==== | ||
- | The @throws | + | @throws |
- | @throwsタグは、「構造的要素」が特定のタイプのエラーをスローすることを示すために使用される場合があります( '' | + | このタグで提供されるタイプは、Throwable のサブタイプであるオブジェクトを表す必要があります( '' |
- | + | ||
- | The type provided with this tag MUST represent an object that is a subtype of 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. | + | このタグは、たとえ同じタイプであっても、例外が発生するたびに提供することをお勧めします( '' |
- | + | ||
- | このタグは、たとえ同じタイプであっても、例外が発生するたびに提供することをお勧めします( '' | + | |
=== 例 ==== | === 例 ==== | ||
行 829: | 行 773: | ||
==== 5.15. @todo ===== | ==== 5.15. @todo ===== | ||
- | The @todo tag is used to indicate whether any development activities should still be executed on associated " | + | @todo タグは、関連する「構造的要素」で開発アクティビティを実行する必要があるかどうかを示すために使用されます。 |
- | + | ||
- | @todoタグは、関連する「構造的要素」で開発アクティビティを実行する必要があるかどうかを示すために使用されます。 | + | |
=== 構文 ==== | === 構文 ==== | ||
行 841: | 行 783: | ||
=== 説明 ==== | === 説明 ==== | ||
- | The @todo tag is used to indicate that an activity surrounding the associated " | + | @todo タグは、関連する「構造的要素」を取り巻くアクティビティが引き続き発生する必要があることを示すために使用されます。各タグには、原作者の意図を伝える説明を添付する必要があります( |
- | + | ||
- | @todoタグは、関連する「構造的要素」を取り巻くアクティビティが引き続き発生する必要があることを示すために使用されます。各タグには、原作者の意図を伝える説明を添付する必要があります( MUST )。ただし、これは問題番号を提供するのと同じくらい短い場合があります。 | + | |
=== 例 ==== | === 例 ==== | ||
行 864: | 行 804: | ||
==== 5.16. @uses ===== | ==== 5.16. @uses ===== | ||
- | |||
- | Indicates whether the current " | ||
現在の「構造的要素」がターゲットとして提供されている「構造的要素」またはプロジェクトファイルを使用するかどうかを示します。 | 現在の「構造的要素」がターゲットとして提供されている「構造的要素」またはプロジェクトファイルを使用するかどうかを示します。 | ||
行 876: | 行 814: | ||
=== 説明 ==== | === 説明 ==== | ||
- | |||
- | The @uses tag describes whether any part of the associated " | ||
'' | '' | ||
- | |||
- | When defining a reference to another " | ||
別の「構造的要素」への参照を定義する場合、二重のコロンを追加し、その要素の名前(「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. | + | このタグは、システム外の要素との関係を示すために使用してはならないため( '' |
- | + | ||
- | このタグは、システム外の要素との関係を示すために使用してはならないため( '' | + | |
- | + | ||
- | 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. | + | |
ジェネレータなど、このタグを使用するアプリケーションは、宛先要素に '' | ジェネレータなど、このタグを使用するアプリケーションは、宛先要素に '' | ||
行 923: | 行 851: | ||
==== 5.17. @var ===== | ==== 5.17. @var ===== | ||
- | You may use the @var tag to document the " | + | @var タグを使用して、次の「構造的要素」の「タイプ」を文書化できます。 |
- | @varタグを使用して、次の「構造的要素」の「タイプ」を文書化できます。 | + | |
- | + | ||
- | + | ||
- | * Constants, both class and global scope | + | |
- | * Properties | + | |
- | * Variables, both global and local scope | + | |
- | + | ||
- | | + | |
* プロパティ | * プロパティ | ||
- | * 変数、グローバルスコープとローカルスコープの両方 | + | * 変数、グローバルスコープ と ローカルスコープ の両方 |
=== 構文 ==== | === 構文 ==== | ||
行 944: | 行 865: | ||
=== 説明 ==== | === 説明 ==== | ||
- | The @var tag defines which type of data is represented by a value of a Constant, Property or Variable. | + | @var タグは、定数、プロパティ、または変数の値によって表されるデータのタイプを定義します。 |
- | + | ||
- | @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を付けるべきです( '' | + | |
- | + | ||
- | 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タグには、ドキュメント化する要素の名前を含める必要があります( '' | + | 型が曖昧または不明である各定数またはプロパティ定義、または変数の前には、@var タグを含むDocBlockを付けるべきです( '' |
- | 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. | + | @var タグには、ドキュメント化する要素の名前を含める必要があります( '' |
- | これは、複合ステートメントを使用して一連の定数またはプロパティを定義するときに使用されます。このような複合ステートメントは、複数のアイテムが表されている間、DocBlockを1つだけ持つことができます。 | + | これは、複合ステートメントを使用して一連の定数またはプロパティを定義するときに使用されます。このような複合ステートメントは、複数のアイテムが表されている間、DocBlock を1つだけ持つことができます。 |
=== 例 ==== | === 例 ==== | ||
<code php> | <code php> | ||
- | /** @var int $intこれはカウンターです。 */ | + | /** @var int $int これはカウンターです。 */ |
$int = 0; | $int = 0; | ||
- | // there should be no docblock here | + | // ここには docblock があるべきではありません |
- | // ここにはdocblockがあるべきではありません | + | |
$int++; | $int++; | ||
</ | </ | ||
行 983: | 行 895: | ||
public function setDescription($description) | public function setDescription($description) | ||
{ | { | ||
- | | + | // ここには docblock があるべきではありません |
- | | + | |
$this-> | $this-> | ||
} | } | ||
行 990: | 行 901: | ||
</ | </ | ||
- | Another example is to document the variable in a foreach explicitly; many IDEs use this information to help you with auto-completion: | + | 他の例としては、foreach 中の変数を明示的に文書化することです。多くの IDE はこの情報を使用して、オートコンプリートを支援します: |
- | + | ||
- | 他の例としては、foreach中の変数を明示的に文書化することです。多くのIDEはこの情報を使用して、オートコンプリートを支援します: | + | |
<code php> | <code php> | ||
/** @var \Sqlite3 $sqlite */ | /** @var \Sqlite3 $sqlite */ | ||
foreach ($connections as $sqlite) { | foreach ($connections as $sqlite) { | ||
- | | + | // ここには docblock があるべきではありません |
- | | + | |
$sqlite-> | $sqlite-> | ||
<...> | <...> | ||
} | } | ||
</ | </ | ||
- | |||
- | Even compound statements may be documented: | ||
複合ステートメントでも文書化できます: | 複合ステートメントでも文書化できます: | ||
行 1047: | 行 953: | ||
==== 5.18. @version ===== | ==== 5.18. @version ===== | ||
+ | |||
+ | @version タグは、要素に対する「バージョニング」の説明を示すために使用されます。 | ||
=== 構文 ==== | === 構文 ==== | ||
<code php> | <code php> | ||
+ | @version [" | ||
</ | </ | ||
=== 説明 ==== | === 説明 ==== | ||
+ | |||
+ | 要素の現在の「バージョン」を文書化します。 | ||
+ | |||
+ | この情報を使用して、特定のバージョンの要素についてコンシューマに通知するAPIドキュメントのセットを生成できます。 | ||
+ | |||
+ | [[https:// | ||
+ | |||
+ | バージョン管理システムのバージョンベクトルもサポートされていますが、次の形式に従う必要があります( '' | ||
+ | |||
+ | <code php> | ||
+ | name-of-vcs: | ||
+ | </ | ||
+ | |||
+ | バージョン固有の追加情報を伝える目的で、説明が提供される場合があります( '' | ||
+ | |||
+ | @version タグは、要素の最終変更バージョンまたは導入バージョンを示すために使用することはできません( '' | ||
=== 例 ==== | === 例 ==== | ||
<code php> | <code php> | ||
+ | /** | ||
+ | * Fooクラスのファイル | ||
+ | * @version 2.1.7 MyApp | ||
+ | | ||
+ | * @version @package_version@ | ||
+ | | ||
+ | * @version $Id$ | ||
+ | | ||
+ | */ | ||
+ | |||
+ | /** | ||
+ | * これはFooです | ||
+ | */ | ||
+ | class Foo | ||
+ | { | ||
+ | <...> | ||
+ | } | ||
</ | </ | ||