このページの2つのバージョン間の差分を表示します。
両方とも前のリビジョン 前のリビジョン 次のリビジョン | 前のリビジョン | ||
psr:psr19 [2020/09/17 11:13] y2sunlight [5.13. @since] |
psr:psr19 [2020/09/17 11:43] (現在) y2sunlight |
||
---|---|---|---|
行 1: | 行 1: | ||
- | > 編集中 | ||
- | |||
====== PSR-19: PHPDoc tags(Draft) ====== | ====== PSR-19: PHPDoc tags(Draft) ====== | ||
行 700: | 行 698: | ||
この情報を使用して、特定の要素に対して必要なアプリケーションバージョンをコンシューマに通知する一連のAPIドキュメントを生成できます。 | この情報を使用して、特定の要素に対して必要なアプリケーションバージョンをコンシューマに通知する一連のAPIドキュメントを生成できます。 | ||
- | 要素の現在のバージョンを表示するために @since タグを使用すべきではありません( '' | + | 要素の現在のバージョンを表示するために @since タグを使用すべきではありません( '' |
=== 例 ==== | === 例 ==== | ||
行 733: | 行 731: | ||
==== 5.14. @throws ===== | ==== 5.14. @throws ===== | ||
- | The @throws tag is used to indicate whether " | + | @throws タグは「構造的要素」が特定のタイプの Throwable(例外またはエラー)をスローするかどうかを示すために使用されます。 |
- | + | ||
- | @throwsタグは、「構造的要素」が特定のタイプのThrowable(例外またはエラー)をスローするかどうかを示すために使用されます。 | + | |
=== 構文 ==== | === 構文 ==== | ||
行 745: | 行 741: | ||
=== 説明 ==== | === 説明 ==== | ||
- | 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. | + | このタグは、たとえ同じタイプであっても、例外が発生するたびに提供することをお勧めします( '' |
- | + | ||
- | このタグは、たとえ同じタイプであっても、例外が発生するたびに提供することをお勧めします( '' | + | |
=== 例 ==== | === 例 ==== | ||
行 783: | 行 771: | ||
==== 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タグは、関連する「構造的要素」で開発アクティビティを実行する必要があるかどうかを示すために使用されます。 | + | |
=== 構文 ==== | === 構文 ==== | ||
行 795: | 行 781: | ||
=== 説明 ==== | === 説明 ==== | ||
- | The @todo tag is used to indicate that an activity surrounding the associated " | + | @todo タグは、関連する「構造的要素」を取り巻くアクティビティが引き続き発生する必要があることを示すために使用されます。各タグには、原作者の意図を伝える説明を添付する必要があります( |
- | + | ||
- | @todoタグは、関連する「構造的要素」を取り巻くアクティビティが引き続き発生する必要があることを示すために使用されます。各タグには、原作者の意図を伝える説明を添付する必要があります( MUST )。ただし、これは問題番号を提供するのと同じくらい短い場合があります。 | + | |
=== 例 ==== | === 例 ==== | ||
行 818: | 行 802: | ||
==== 5.16. @uses ===== | ==== 5.16. @uses ===== | ||
- | |||
- | Indicates whether the current " | ||
現在の「構造的要素」がターゲットとして提供されている「構造的要素」またはプロジェクトファイルを使用するかどうかを示します。 | 現在の「構造的要素」がターゲットとして提供されている「構造的要素」またはプロジェクトファイルを使用するかどうかを示します。 | ||
行 830: | 行 812: | ||
=== 説明 ==== | === 説明 ==== | ||
- | |||
- | 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. | + | |
ジェネレータなど、このタグを使用するアプリケーションは、宛先要素に '' | ジェネレータなど、このタグを使用するアプリケーションは、宛先要素に '' | ||
行 877: | 行 849: | ||
==== 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 | + | |
- | + | ||
- | | + | |
* プロパティ | * プロパティ | ||
- | * 変数、グローバルスコープとローカルスコープの両方 | + | * 変数、グローバルスコープ と ローカルスコープ の両方 |
=== 構文 ==== | === 構文 ==== | ||
行 898: | 行 863: | ||
=== 説明 ==== | === 説明 ==== | ||
- | The @var tag defines which type of data is represented by a value of a Constant, Property or Variable. | + | @var タグは、定数、プロパティ、または変数の値によって表されるデータのタイプを定義します。 |
- | @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 | + | @var タグには、ドキュメント化する要素の名前を含める必要があります( '' |
- | 型があいまいまたは不明である各定数またはプロパティ定義または変数の前には、@varタグを含むDocBlockを付けるべきです( '' | + | これは、複合ステートメントを使用して一連の定数またはプロパティを定義するときに使用されます。このような複合ステートメントは、複数のアイテムが表されている間、DocBlock を1つだけ持つことができます。 |
- | + | ||
- | 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タグには、ドキュメント化する要素の名前を含める必要があります( '' | + | |
- | + | ||
- | 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つだけ持つことができます。 | + | |
=== 例 ==== | === 例 ==== | ||
<code php> | <code php> | ||
- | /** @var int $intこれはカウンターです。 */ | + | /** @var int $int これはカウンターです。 */ |
$int = 0; | $int = 0; | ||
- | // there should be no docblock here | + | // ここには docblock があるべきではありません |
- | // ここにはdocblockがあるべきではありません | + | |
$int++; | $int++; | ||
</ | </ | ||
行 937: | 行 893: | ||
public function setDescription($description) | public function setDescription($description) | ||
{ | { | ||
- | | + | // ここには docblock があるべきではありません |
- | | + | |
$this-> | $this-> | ||
} | } | ||
行 944: | 行 899: | ||
</ | </ | ||
- | 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: | ||
複合ステートメントでも文書化できます: | 複合ステートメントでも文書化できます: | ||
行 1002: | 行 952: | ||
==== 5.18. @version ===== | ==== 5.18. @version ===== | ||
- | The @version tag is used to denote some description of " | + | @version タグは、要素に対する「バージョニング」の説明を示すために使用されます。 |
- | + | ||
- | @versionタグは、要素に対する「バージョニング」の説明を示すために使用されます。 | + | |
=== 構文 ==== | === 構文 ==== | ||
行 1013: | 行 961: | ||
=== 説明 ==== | === 説明 ==== | ||
- | |||
- | Documents the current " | ||
要素の現在の「バージョン」を文書化します。 | 要素の現在の「バージョン」を文書化します。 | ||
- | |||
- | This information can be used to generate a set of API Documentation where the consumer is informed about elements at a particular version. | ||
この情報を使用して、特定のバージョンの要素についてコンシューマに通知するAPIドキュメントのセットを生成できます。 | この情報を使用して、特定のバージョンの要素についてコンシューマに通知するAPIドキュメントのセットを生成できます。 | ||
- | It is RECOMMENDED that the version number matches a semantic version number as described in the Semantic Versioning Standard version 2.0. | + | [[https:// |
- | [[https:// | + | バージョン管理システムのバージョンベクトルもサポートされていますが、次の形式に従う必要があります( '' |
- | Version vectors from Version Control Systems are also supported, though they MUST follow the form: | + | < |
- | + | ||
- | バージョン管理システムのバージョンベクターもサポートされていますが、次の形式に従う必要があります( '' | + | |
- | + | ||
- | < | + | |
name-of-vcs: | name-of-vcs: | ||
</ | </ | ||
- | |||
- | A description MAY be provided, for the purpose of communicating any additional version-specific information. | ||
バージョン固有の追加情報を伝える目的で、説明が提供される場合があります( '' | バージョン固有の追加情報を伝える目的で、説明が提供される場合があります( '' | ||
- | 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 タグは、要素の最終変更バージョンまたは導入バージョンを示すために使用することはできません( '' |
- | + | ||
- | @versionタグは、要素の最終変更バージョンまたは導入バージョンを示すために使用することはできません( '' | + | |
=== 例 ==== | === 例 ==== |