Ground Sunlight

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

ユーザ用ツール

サイト用ツール

トレース:
psr:psr19

差分

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

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

両方とも前のリビジョン 前のリビジョン
次のリビジョン 		前のリビジョン
psr:psr19 [2020/09/16 12:46]
tanaka [5.13. @since] 		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 "magic" properties are supported. +''@property'' タグはどんな「マジック」プロパティがサポートされているのかを宣言するために使用されます。
- +
-''@property'' タグは、サポートされている「マジック」プロパティを宣言するために使用されます。+
  
 === 構文 ==== === 構文 ====
行 562: 行 558:
 === 説明 ==== === 説明 ====
  
-The @property tag is used when a class (or trait) implements the <nowiki>__get()</nowiki> and/or <nowiki>__set()</nowiki> "magic" methods to resolve non-literal properties at run-time. +''@property'' タグは、''クラス''（または''トレイト''）が ''<nowiki>__get()</nowiki>'' または ''<nowiki>__set()</nowiki>'' の「マジック」メソッドを実装して、実行時に非リテラルプロパティを解決するときに使用されます。
- +
-''@property'' タグは、''クラス''（または''トレイト''）が ''<nowiki>__get()</nowiki>'' または ''<nowiki>__set()</nowiki>'' の「マジック」メソッドを実装して実行時に非リテラルプロパティを解決するときに使用されます。 +
- +
-The @property-read and @property-write variants MAY be used to indicate "magic" properties that can only be read or written.+
  
 ''@property-read'' および ''@property-write'' バリアントは、読み取りまたは書き込みのみが可能な「マジック」プロパティを示すために使用される場合があります( ''MAY'' )。 ''@property-read'' および ''@property-write'' バリアントは、読み取りまたは書き込みのみが可能な「マジック」プロパティを示すために使用される場合があります( ''MAY'' )。
- 
-The @property tags can ONLY be used in a PHPDoc that is associated with a class or trait. 
  
 ''@property'' タグは、クラスまたはトレイトに関連付けられているPHPDocでのみ使用できます。 ''@property'' タグは、クラスまたはトレイトに関連付けられているPHPDocでのみ使用できます。
  
 === 例 ==== === 例 ====
- 
-In the following example, a class User implements the magic <nowiki>__get()</nowiki> method, in order to implement a "magic", read-only $full_name property: 
  
 次の例では、クラス ''User'' がマジックの<nowiki>__get()</nowiki>メソッドを実装して、「マジック」の読み取り専用の ''$full_name'' プロパティを実装しています： 次の例では、クラス ''User'' がマジックの<nowiki>__get()</nowiki>メソッドを実装して、「マジック」の読み取り専用の ''$full_name'' プロパティを実装しています：
行 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 "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」に限定されます。
行 665: 行 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サイトまたはその他の「構造的要素」への参照を示します。+
  
 === 構文 ==== === 構文 ====
行 679: 行 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'' )。+
  
 === 例 ==== === 例 ====
行 699: 行 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()
行 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 "versioning" to that element. +@since タグは、要素の「バージョニング」の説明を使用して、要素がいつ導入または変更されたかを示すために使用されます。
- +
-@sinceタグは、要素の「バージョニング」の説明を使用して、要素がいつ導入または変更されたかを示すために使用されます。+
  
 === 構文 ==== === 構文 ====
行 731: 行 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'' )。+
  
 === 例 ==== === 例 ====
行 778: 行 730:
  
 ==== 5.14. @throws ===== ==== 5.14. @throws =====
 +
 +@throws タグは「構造的要素」が特定のタイプの Throwable（例外またはエラー）をスローするかどうかを示すために使用されます。
  
 === 構文 ==== === 構文 ====
  
 <code php> <code php>
 +@throws ["Type"] [<description>]
 </code> </code>
  
 === 説明 ==== === 説明 ====
 +
 +@throws タグは「構造的要素」が特定のタイプのエラーをスローすることを示すために使用できます( ''MAY'' )。
 +
 +このタグで提供されるタイプは、Throwable のサブタイプであるオブジェクトを表す必要があります( ''MUST'' )。
 +
 +このタグは、ドキュメントの中で、どのエラーが発生し、どのような状況で発生するかを示すために使用されます。例外がスローされる理由の説明を提供することをお勧めします( ''RECOMMENDED'' )。
 +
 +このタグは、たとえ同じタイプであっても、例外が発生するたびに提供することをお勧めします( ''RECOMMENDED'' )。すべての発生を文書化することにより、詳細なビューが作成され、コンシューマはどのエラーをチェックすれば良いかを知ることができます。
  
 === 例 ==== === 例 ====
  
 <code php> <code php>
 +/**
 + * 指定された配列内のアイテムの数をカウントします。
 + *
 + * @param mixed[] $array 要素をカウントする配列構造。
 + *
 + * @throws InvalidArgumentException 与えられた引数が'array'タイプではない場合。
 + *
 + * @return int 要素の数を返します。
 + */
 +function count($items)
 +{
 +    <...>
 +}
 </code> </code>
  
行 794: 行 770:
  
 ==== 5.15. @todo ===== ==== 5.15. @todo =====
 +
 +@todo タグは、関連する「構造的要素」で開発アクティビティを実行する必要があるかどうかを示すために使用されます。
  
 === 構文 ==== === 構文 ====
  
 <code php> <code php>
 +@todo [description]
 </code> </code>
  
 === 説明 ==== === 説明 ====
 +
 +@todo タグは、関連する「構造的要素」を取り巻くアクティビティが引き続き発生する必要があることを示すために使用されます。各タグには、原作者の意図を伝える説明を添付する必要があります( ''MUST'' )。ただし、これは問題番号を提供するのと同じくらい短い場合があります。
  
 === 例 ==== === 例 ====
  
 <code php> <code php>
 +/**
 + * 指定された配列内のアイテムの数をカウントします。
 + *
 + * @todo カウントする配列パラメーターを追加する
 + *
 + * @return int 要素の数を返します。
 + */
 +function count()
 +{
 +    <...>
 +}
 </code> </code>
  
行 810: 行 802:
  
 ==== 5.16. @uses ===== ==== 5.16. @uses =====
 +
 +現在の「構造的要素」がターゲットとして提供されている「構造的要素」またはプロジェクトファイルを使用するかどうかを示します。
  
 === 構文 ==== === 構文 ====
  
 <code php> <code php>
 +@uses [file | "FQSEN"] [<description>]
 </code> </code>
  
 === 説明 ==== === 説明 ====
 +
 +''@uses'' タグは、関連する「構造的要素」の一部が別の「構造的要素」または現在のプロジェクトにあるファイルを使用するかどうかを示します。
 +
 +別の「構造的要素」への参照を定義する場合、二重のコロンを追加し、その要素の名前（「FQSEN」とも呼ばれる）を指定することにより、特定の要素を参照できます。
 +
 +このプロジェクトに含まれるファイルは、このタグで参照できます。これは、例えば、コントローラーと（ビューとしての）テンプレートファイルの間の関係を示すために使用できます。
 +
 +このタグは、システム外の要素との関係を示すために使用してはならないため( ''MUST NOT'' )、URLは使用できません。外部要素との関係を示すには、@see タグを使用できます。
 +
 +ジェネレータなど、このタグを使用するアプリケーションは、宛先要素に ''@used-by'' タグを提供することをお勧めします( ''RECOMMENDED'' )。これは、双方向のエクスペリエンスを提供し、静的分析を可能にするために使用できます。
  
 === 例 ==== === 例 ====
  
 <code php> <code php>
 +/**
 + * @uses \SimpleXMLElement::__construct() ※FQSENの例
 + */
 +function initializeXml()
 +{
 +    <...>
 +}
 +</code>
 +
 +<code php>
 +/**
 + * @uses MyView.php ※ファイルの例
 + */
 +function executeMyView()
 +{
 +    <...>
 +}
 </code> </code>
  
行 826: 行 848:
  
 ==== 5.17. @var ===== ==== 5.17. @var =====
 +
 +@var タグを使用して、次の「構造的要素」の「タイプ」を文書化できます。
 +
 +  * クラススコープ と グローバルスコープ の両方の定数
 +  * プロパティ
 +  * 変数、グローバルスコープ と ローカルスコープ の両方
  
 === 構文 ==== === 構文 ====
  
 <code php> <code php>
 +@var ["Type"] [element_name] [<description>]
 </code> </code>
  
 === 説明 ==== === 説明 ====
 +
 +@var タグは、定数、プロパティ、または変数の値によって表されるデータのタイプを定義します。
 +
 +型が曖昧または不明である各定数またはプロパティ定義、または変数の前には、@var タグを含むDocBlockを付けるべきです( ''SHOULD'' )。他の変数の前にも、@varタグを含むDocBlockを付けることができます( ''MAY'' )。
 +
 +@var タグには、ドキュメント化する要素の名前を含める必要があります( ''MUST'' )。これの例外は、プロパティ宣言が単一のプロパティのみを参照する場合です。この場合、プロパティの名前は省略できます( ''MAY'' )。
 +
 +これは、複合ステートメントを使用して一連の定数またはプロパティを定義するときに使用されます。このような複合ステートメントは、複数のアイテムが表されている間、DocBlock を1つだけ持つことができます。
  
 === 例 ==== === 例 ====
  
 <code php> <code php>
 +/** @var int $int これはカウンターです。 */
 +$int = 0;
 +
 +// ここには docblock があるべきではありません
 +$int++;
 +</code>
 +
 +Or:
 +
 +または：
 +
 +<code php>
 +class Foo
 +{
 +  /** @var string|null 説明を含める必要があります */
 +  protected $description = null;
 +
 +  public function setDescription($description)
 +  {
 +      // ここには docblock があるべきではありません
 +      $this->description = $description;
 +  }
 +}
 +</code>
 +
 +他の例としては、foreach 中の変数を明示的に文書化することです。多くの IDE はこの情報を使用して、オートコンプリートを支援します：
 +
 +<code php>
 +/** @var \Sqlite3 $sqlite */
 +foreach ($connections as $sqlite) {
 +    // ここには docblock があるべきではありません
 +    $sqlite->open('/my/database/path');
 +    <...>
 +}
 +</code>
 +
 +複合ステートメントでも文書化できます：
 +
 +<code php>
 +class Foo
 +{
 +  protected
 +      /**
 +       * @var string 説明を含める必要があります
 +       */
 +      $name,
 +      /**
 +       * @var string 説明を含める必要があります
 +       */
 +      $description;
 +
 +}
 +</code>
 +
 +Or constants:
 +
 +または定数の場合：
 +
 +<code php>
 +class Foo
 +{
 +  const
 +      /**
 +       * @var string 説明を含める必要があります
 +       */
 +      MY_CONST1 = "1",
 +      /**
 +       * @var string 説明を含める必要があります
 +       */
 +      MY_CONST2 = "2";
 +
 +}
 </code> </code>
  
行 842: 行 951:
  
 ==== 5.18. @version ===== ==== 5.18. @version =====
 +
 +@version タグは、要素に対する「バージョニング」の説明を示すために使用されます。
  
 === 構文 ==== === 構文 ====
  
 <code php> <code php>
 +@version ["Semantic Version"] [<description>]
 </code> </code>
  
 === 説明 ==== === 説明 ====
 +
 +要素の現在の「バージョン」を文書化します。
 +
 +この情報を使用して、特定のバージョンの要素についてコンシューマに通知するAPIドキュメントのセットを生成できます。
 +
 +[[https://semver.org/|Semantic Versioning Standard version 2.0]] で説明されているように、バージョン番号がセマンティックバージョン番号と一致することが推奨されます( ''RECOMMENDED'' )。
 +
 +バージョン管理システムのバージョンベクトルもサポートされていますが、次の形式に従う必要があります( ''MUST'' )。
 +
 +<code>
 +name-of-vcs: $vector$
 +</code>
 +
 +バージョン固有の追加情報を伝える目的で、説明が提供される場合があります( ''MAY'' )。
 +
 +@version タグは、要素の最終変更バージョンまたは導入バージョンを示すために使用することはできません( ''MAY NOT'' )。@sinceタグを、その目的で使用すべきです( ''SHOULD'' )。
  
 === 例 ==== === 例 ====
  
 <code php> <code php>
 +/**
 + * Fooクラスのファイル
 + * @version 2.1.7 MyApp
 + *          (この文字列は、アプリケーションの全体的なバージョン番号を示します)
 + * @version @package_version@
 + *          (このPEAR置換キーワードは、パッケージのインストール時に拡張されます)　※バージョンベクターの例（PEAR）
 + * @version $Id$
 + *          (このCVSキーワードは、CVSファイルのリビジョン番号を表示するように展開されます)　 ※バージョンベクターの例（CVS）
 + */
 +
 +/**
 + * これはFooです
 + */
 +class Foo
 +{
 +  <...>
 +}
 </code> </code>
  
psr/psr19.1600227983.txt.gz · 最終更新: 2020/09/16 12:46 by tanaka

ページ用ツール

特に明示されていない限り、本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