基本文法¶

Docブロックって何？¶

A DocBlock is a special type of comment that can provide verbose information about an element in your code.

Docブロックはコードに詳細な情報を記述することができる、特別な種類のコメント文です。

The information provided in this type of comment can be used by developers to gain understanding of the function of a given element; but it is also used by IDEs to provide (among others) auto-completion and by phpDocumentor to generate API documentation.

このコメントは機能についての理解を促進させる情報を提供するために利用されます。 DocコメントをもとにIDEが自動補完の手がかりとしたり、phpDocumentorがAPIドキュメントを生成します。

This is an example of a DocBlock as it can be encountered:

よく見られるDocコメントの例です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

 /**
  * This is the summary for a DocBlock.
  *
  * This is the description for a DocBlock. This text may contain
  * multiple lines and even some _markdown_.
  *
  * * Markdown style lists function too
  * * Just try this out once
  *
  * The section after the description contains the tags; which provide
  * structured meta-data concerning the given element.
  *
  * @author  Mike van Riel <me@mikevanriel.com>
  *
  * @since 1.0
  *
  * @param int    $example  This is an example function/method parameter description.
  * @param string $example2 This is a second example.
  */

 /**
  * これはDocブロックの要約です
  *
  * これはDocブロックの説明です。このテキストは複数行を含み、
  * _markdown_ を含んでも良いです。
  *
  * * Markdown風のリスト機能もある
  * * 一度試してみてね
  *
  * 説明文のあとにはタグを含みます。
  * タグによって構造化されたメタデータを記述できます。
  *
  * @author  Mike van Riel <me@mikevanriel.com>
  *
  * @since 1.0
  *
  * @param int    $example  これは函数/メソッドの引数の説明文の例です。
  * @param string $example2 これはふたつめの例です。
  */

Docブロックにはどんな要素を含むか¶

Structural Elements can all be preceded by a DocBlock. The following elements are counted as such:

構造的な要素にはDocブロックを前置することができます。それは以下のような要素です

• 名前空間 / namespace
• require(_once)
• include(_once)
• クラス / class
• インターフェイス / interface
• トレイト / trait
• 函数 / function (メソッドを含む)
• プロパティ / property
• 定数 / constant
• 変数(ローカルおよびグローバル) / variables, both local and global scope.

A more detailed description of what Structural Elements are and how DocBlocks apply to them can be found in the Definitions.

Structural Elements が何かについての詳細な説明は Definitions にあります。

セクション / Sections¶

A DocBlock roughly exists of 3 sections:

Docブロックには、およそ三つのセクションがあります。

1. Summary; a one-liner which globally states the function of the documented element.

   要約： 文書化された要素の機能についての概要を一行で記述します

2. Description; an extended description of the function of the documented element; may contain markup and inline tags.

   説明文： 文書化された要素の機能について追加で説明します。文中にマーク付けとインラインタグを含むことができます。

3. Tags; a series of descriptors for properties of this element; such as @param and @return.

   タグ： 文書化された要素の機能の性質について記述するもので、 @param や @return などがあります。

Inheritance¶

Docblocks automatically inherit the Summary and Description of an overridden, extended or implemented element.

For example: if Class B extends Class A and it has an empty DocBlock defined, then it will have the same Summary and Description as Class A. No DocBlock means that the ‘parent’ DocBlock will not be overridden and an error will be thrown during parsing.

This form of inheritance applies to any element that can be overridden, such as Classes, Interfaces, Methods and Properties. Constants and Functions can not be overridden in and thus do not have this behavior.

Please note that you can also augment a Description with its parent’s Description using the {@inheritdoc} inline tag.

Each element also inherits a specific set of tags; which ones depend on the type of element.

The following applies:

Please note that @subpackage tags are only inherited if the parent class has the same @package. Otherwise it is assumed that the parent class is part of a library which might have a different structure.