Ground Sunlight

Windowsで作る - PHPプログラミングの開発環境

ユーザ用ツール

サイト用ツール

トレース:
psr:psr19

差分

このページの2つのバージョン間の差分を表示します。

この比較画面にリンクする

両方とも前のリビジョン 前のリビジョン
次のリビジョン 		前のリビジョン
psr:psr19 [2020/09/17 10:22]
y2sunlight [5.10. @property] 		psr:psr19 [2020/09/17 11:43] (現在)
y2sunlight
行 1: 行 1:
-> 編集中 
- 
 ====== PSR-19: PHPDoc tags(Draft) ====== ====== PSR-19: PHPDoc tags(Draft) ======
  
行 598: 行 596:
  
 ==== 5.11. @return ===== ==== 5.11. @return =====
- 
-The @return tag is used to document the return value of functions or methods. 
  
 @returnタグは、関数またはメソッドの戻り値を文書化するために使用されます。 @returnタグは、関数またはメソッドの戻り値を文書化するために使用されます。
行 611: 行 607:
 === 説明 ==== === 説明 ====
  
-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'' )。
- +
-@returnタグを使用すると、関数またはメソッドの戻り値の型を文書化できます。指定する場合は、返されるものを示す「タイプ」を含める必要があります( ''MUST'' )。一方、連想配列などの複雑な戻り構造の場合、説明はオプションですが( ''OPTIONAL'' )、推奨されます( ''RECOMMENDED'' )。 +
- +
-The @return tag MAY have a multi-line description and does not need explicit delimiting.+
  
 @returnタグには複数行の説明が含まれる場合があり( ''MAY'' )、明示的な区切りは必要ありません。 @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'' )： すべての関数とメソッドでこのタグを使用することをお勧めします( ''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'' )。
- +
-**戻り値のない関数とメソッド**：@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」に限定されます。 このタグは「DocBlock」内で2回以上出現してはならず( ''MUST NOT'' )、メソッドまたは関数の「構造的要素」の「DocBlock」に限定されます。
行 655: 行 641:
 ==== 5.12. @see ===== ==== 5.12. @see =====
  
-The @see tag indicates a reference from the associated "Structural Elements" to a website or other "Structural Elements". +@see タグは、関連する「構造的要素」からWebサイトまたはその他の「構造的要素」への参照を示します。
- +
-@seeタグは、関連する「構造的要素」からWebサイトまたはその他の「構造的要素」への参照を示します。+
  
 === 構文 ==== === 構文 ====
行 669: 行 653:
 === 説明 ==== === 説明 ====
  
-The @see tag can be used to define a reference to other "Structural Elements" or to a URI. +@see タグを使用して、他の「構造的要素」または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」とも呼ばれる）を指定することにより、特定の要素を参照できます。 別の「構造的要素」への参照を定義する場合、二重コロンを追加してその要素の名前（「FQSEN」とも呼ばれる）を指定することにより、特定の要素を参照できます。
- 
-A URI MUST be complete and well-formed as specified in RFC 2396. 
  
 [[https://tools.ietf.org/html/rfc2396|RFC 2396]]で指定されているように、URIは完全かつ整形式でなければなりません( ''MUST'' )。 [[https://tools.ietf.org/html/rfc2396|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タグは、要素とそのターゲットの間の関係に関する追加情報を提供する説明をすべきです( ''SHOULD'' )。さらに、@seeタグには、この関係にさらに定義を追加するためのタグの特殊化がある場合があります( ''MAY'' )。+
  
 === 例 ==== === 例 ====
行 689: 行 665:
 <code php> <code php>
 /** /**
- * @see number_of() :alias:       ※特殊化の例 + * @see number_of() :alias:       （ ※特殊化の例 ） 
- * @see MyClass::$items           For the property whose items are counted. + * @see MyClass::$items           アイテムがカウントされるプロパティ。（ ※FQSENの例（プロパティ）） 
- *                                アイテムがカウントされるプロパティ。※FQSENの例（プロパティ） + * @see MyClass::setItems()       このコレクションのアイテムを設定します。（ ※FQSENの例（メソッド）） 
- * @see MyClass::setItems()       To set the items for this collection. + * @see http://example.com/my/bar Fooのドキュメント。（ ※URLの例 ）
- *                                このコレクションのアイテムを設定します。※FQSENの例（メソッド） +
- * @see http://example.com/my/bar Documentation of Foo. +
- *                                Fooのドキュメント。※URLの例+
  *  *
- * @return int Indicates the number of items. + * @return int アイテムの数を示します。
- *             アイテムの数を示します。+
  */  */
 function count() function count()
行 710: 行 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 "versioning" to that element. +@since タグは、要素の「バージョニング」の説明を使用して、要素がいつ導入または変更されたかを示すために使用されます。
- +
-@sinceタグは、要素の「バージョニング」の説明を使用して、要素がいつ導入または変更されたかを示すために使用されます。+
  
 === 構文 ==== === 構文 ====
行 721: 行 691:
  
 === 説明 ==== === 説明 ====
- 
-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'' )。
- +
-このバージョンは、セマンティックバージョン番号（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ドキュメントを生成できます。 この情報を使用して、特定の要素に対して必要なアプリケーションバージョンをコンシューマに通知する一連の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'' )。
- +
-要素の現在のバージョンを表示するために@sinceタグを使用すべきではありません( ''SHOULD NOT'' )。@versionタグはその目的で使用できます( ''MAY'' )。+
  
 === 例 ==== === 例 ====
行 769: 行 731:
 ==== 5.14. @throws ===== ==== 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タグは、「構造的要素」が特定のタイプのThrowable（例外またはエラー）をスローするかどうかを示すために使用されます。+
  
 === 構文 ==== === 構文 ====
行 781: 行 741:
 === 説明 ==== === 説明 ====
  
-The @throws tag MAY be used to indicate that "Structural Elements" throw a specific type of error.+@throws タグは「構造的要素」が特定のタイプのエラーをスローすることを示すために使用できます( ''MAY'' )。
  
-@throwsタグは、「構造的要素」が特定のタイプのエラーをスローすることを示すために使用される場合があります( ''MAY'' )。 +このタグで提供されるタイプは、Throwable のサブタイプであるオブジェクトを表す必要があります( ''MUST'' )。
- +
-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'' )。 このタグは、ドキュメントの中で、どのエラーが発生し、どのような状況で発生するかを示すために使用されます。例外がスローされる理由の説明を提供することをお勧めします( ''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'' )。すべての発生を文書化することにより、詳細なビューが作成され、コンシューマはどのエラーをチェックすれば良いかを知ることができます。
- +
-このタグは、たとえ同じタイプであっても、例外が発生するたびに提供することをお勧めします( ''RECOMMENDED'' )。すべての発生を文書化することにより、詳細なビューが作成され、コンシューマはどのエラーをチェックするかを知ることができます。+
  
 === 例 ==== === 例 ====
行 819: 行 771:
 ==== 5.15. @todo ===== ==== 5.15. @todo =====
  
-The @todo tag is used to indicate whether any development activities should still be executed on associated "Structural Elements". +@todo タグは、関連する「構造的要素」で開発アクティビティを実行する必要があるかどうかを示すために使用されます。
- +
-@todoタグは、関連する「構造的要素」で開発アクティビティを実行する必要があるかどうかを示すために使用されます。+
  
 === 構文 ==== === 構文 ====
行 831: 行 781:
 === 説明 ==== === 説明 ====
  
-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タグは、関連する「構造的要素」を取り巻くアクティビティが引き続き発生する必要があることを示すために使用されます。各タグには、原作者の意図を伝える説明を添付する必要があります( MUST )。ただし、これは問題番号を提供するのと同じくらい短い場合があります。+
  
 === 例 ==== === 例 ====
行 854: 行 802:
  
 ==== 5.16. @uses ===== ==== 5.16. @uses =====
- 
-Indicates whether the current "Structural Element" consumes the "Structural Element", or project file, that is provided as target. 
  
 現在の「構造的要素」がターゲットとして提供されている「構造的要素」またはプロジェクトファイルを使用するかどうかを示します。 現在の「構造的要素」がターゲットとして提供されている「構造的要素」またはプロジェクトファイルを使用するかどうかを示します。
行 866: 行 812:
  
 === 説明 ==== === 説明 ====
- 
-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'' タグは、関連する「構造的要素」の一部が別の「構造的要素」または現在のプロジェクトにあるファイルを使用するかどうかを示します。 ''@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」とも呼ばれる）を指定することにより、特定の要素を参照できます。 別の「構造的要素」への参照を定義する場合、二重のコロンを追加し、その要素の名前（「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 タグを使用できます。
- +
-このタグは、システム外の要素との関係を示すために使用してはならないため( ''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'' )。これは、双方向のエクスペリエンスを提供し、静的分析を可能にするために使用できます。 ジェネレータなど、このタグを使用するアプリケーションは、宛先要素に ''@used-by'' タグを提供することをお勧めします( ''RECOMMENDED'' )。これは、双方向のエクスペリエンスを提供し、静的分析を可能にするために使用できます。
行 913: 行 849:
 ==== 5.17. @var ===== ==== 5.17. @var =====
  
-You may use the @var tag to document the "Type" of the following "Structural Elements":+@var タグを使用して、次の「構造的要素」の「タイプ」を文書化できます。
  
-@varタグを使用して、次の「構造的要素」の「タイプ」を文書化できます。 +  * クラススコープ と グローバルスコープ の両方の定数
- +
- +
-  * Constants, both class and global scope +
-  * Properties +
-  * Variables, both global and local scope +
- +
-  * クラススコープとグローバルスコープの両方の定数+
   * プロパティ   * プロパティ
-  * 変数、グローバルスコープとローカルスコープの両方+  * 変数、グローバルスコープ と ローカルスコープ の両方
  
 === 構文 ==== === 構文 ====
行 934: 行 863:
 === 説明 ==== === 説明 ====
  
-The @var tag defines which type of data is represented by a value of a Constant, Property or Variable.+@var タグは、定数、プロパティ、または変数の値によって表されるデータのタイプを定義します。
  
-@varタグは、定数、プロパティ、または変数の値によって表されるデータのタイプを定義します。+型が曖昧または不明である各定数またはプロパティ定義、または変数の前には、@var タグを含むDocBlockを付けるべきです( ''SHOULD'' )。他の変数の前にも、@varタグを含むDocBlockを付けることができます( ''MAY'' )。
  
-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 タグには、ドキュメント化する要素の名前を含める必要があります( ''MUST'' )。これの例外は、プロパティ宣言が単一のプロパティのみを参照する場合です。この場合、プロパティの名前は省略できます( ''MAY'' )。
  
-型があいまいまたは不明である各定数またはプロパティ定義または変数の前には、@varタグを含むDocBlockを付けるべきです( ''SHOULD'' )。他の変数の前にも、@varタグを含むDocBlockを付けることができます( ''MAY'' )。 +これは、複合ステートメントを使用して一連の定数またはプロパティを定義するときに使用されます。このような複合ステートメントは、複数のアイテムが表されている間、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タグには、ドキュメント化する要素の名前を含める必要があります( ''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つだけ持つことができます。+
  
 === 例 ==== === 例 ====
  
 <code php> <code php>
-/** @var int $intこれはカウンターです。 */+/** @var int $int これはカウンターです。 */
 $int = 0; $int = 0;
  
-// there should be no docblock here +// ここには docblock があるべきではありません
-// ここにはdocblockがあるべきではありません+
 $int++; $int++;
 </code> </code>
行 973: 行 893:
   public function setDescription($description)   public function setDescription($description)
   {   {
-      // there should be no docblock here +      // ここには docblock があるべきではありません
-      // ここにはdocblockがあるべきではありません+
       $this->description = $description;       $this->description = $description;
   }   }
行 980: 行 899:
 </code> </code>
  
-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) {
-    // there should be no docblock here +    // ここには docblock があるべきではありません
-    // ここにはdocblockがあるべきではありません+
     $sqlite->open('/my/database/path');     $sqlite->open('/my/database/path');
     <...>     <...>
 } }
 </code> </code>
- 
-Even compound statements may be documented: 
  
 複合ステートメントでも文書化できます： 複合ステートメントでも文書化できます：
行 1038: 行 952:
 ==== 5.18. @version ===== ==== 5.18. @version =====
  
-The @version tag is used to denote some description of "versioning" to an element. +@version タグは、要素に対する「バージョニング」の説明を示すために使用されます。
- +
-@versionタグは、要素に対する「バージョニング」の説明を示すために使用されます。+
  
 === 構文 ==== === 構文 ====
行 1049: 行 961:
  
 === 説明 ==== === 説明 ====
- 
-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ドキュメントのセットを生成できます。 この情報を使用して、特定のバージョンの要素についてコンシューマに通知するAPIドキュメントのセットを生成できます。
  
-It is RECOMMENDED that the version number matches a semantic version number as described in the Semantic Versioning Standard version 2.0.+[[https://semver.org/|Semantic Versioning Standard version 2.0]] で説明されているように、バージョン番号がセマンティックバージョン番号と一致することが推奨されます( ''RECOMMENDED'' )。
  
-[[https://semver.org/|Semantic Versioning Standard version 2.0]]で説明されているように、バージョン番号がセマンティックバージョン番号と一致することが推奨されます( ''RECOMMENDED'' )。+バージョン管理システムのバージョンベクトルもサポートされていますが、次の形式に従う必要があります( ''MUST'' )。
  
-Version vectors from Version Control Systems are also supported, though they MUST follow the form: +<code>
- +
-バージョン管理システムのバージョンベクターもサポートされていますが、次の形式に従う必要があります( ''MUST'' )。 +
- +
-<code php>+
 name-of-vcs: $vector$ name-of-vcs: $vector$
 </code> </code>
- 
-A description MAY be provided, for the purpose of communicating any additional version-specific information. 
  
 バージョン固有の追加情報を伝える目的で、説明が提供される場合があります( ''MAY'' )。 バージョン固有の追加情報を伝える目的で、説明が提供される場合があります( ''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'' )。
- +
-@versionタグは、要素の最終変更バージョンまたは導入バージョンを示すために使用することはできません( ''MAY NOT'' )。@sinceタグを、その目的で使用すべきです( ''SHOULD'' )。+
  
 === 例 ==== === 例 ====
psr/psr19.1600305720.txt.gz · 最終更新: 2020/09/17 10:22 by y2sunlight

ページ用ツール

特に明示されていない限り、本Wikiの内容は次のライセンスに従います： CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki