This is a special type of comment which starts with /**, ends with */ and may contain any number of lines in between. Every line should start with an asterisk, which is aligned with the first asterisk of the opening clause.
Single line example:
1 | /** <...> */
|
Multiline example:
1 2 3 | /**
* <...>
*/
|
This is a DocComment containing a single PHPDoc and represents the basic in-source representation.
Example:
1 2 3 4 5 | /**
* Returns the name of this object.
*
* @return string
*/
|
phpDocumentor generates a XML file between parsing your source code and generating the HTML output. This structure file (called structure.xml) contains the raw analyzed data of your project, also called: an Abstract Syntax Tree.
This same file is also used by phpDocumentor to do incremental parsing of your project by comparing the contents of this file with the content on disk.
It is thus recommended to keep your structure file and allow phpDocumentor to re-use the contained information.
This is a section of documentation which provides information on several aspects of Structural Elements.
A PHPDoc is usually enveloped in a DocComment.
Example:
1 2 3 | Returns the name of this object.
@return string
|
Example enveloped in a DocComment:
1 2 3 4 5 | /**
* Returns the name of this object.
*
* @return string
*/
|
This is a collection of Programming Constructs which SHOULD be preceded by a DocBlock. The collection contains the following constructs:
Docブロック を前置すべき言語構造の総称です。次のようなものが挙げられます。
It is RECOMMENDED to precede Structural Elements with a DocBlock at its definition and not with each individual usage.
Docブロック は個々の使用箇所ではなく、定義の 構造要素 に記述することを推奨します(RECOMMENDED)。
例：
1 2 3 4 5 | /** @var int This is a counter. */
$int = 0;
// there should be no docblock here
$int++;
|
1 2 3 4 5 | /** @var int これはカウンターです。 */
$int = 0;
// ここにDocブロックは書けません
$int++;
|
または：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | /**
* This class acts as an example on where to position a DocBlock.
*/
class Foo
{
/** @var string|null Should contain a description if available */
protected $description = null;
/**
* This method sets a description.
*
* @param string $description A text with a maximum of 80 characters.
*
* @return void
*/
public function setDescription($description)
{
// there should be no docblock here
$this->description = $description;
}
}
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | /**
* このクラスはDocブロックを書く場所の例です。
*/
class Foo
{
/** @var string|null 有効なら説明文を持つべきです */
protected $description = null;
/**
* このメソッドには説明文が設定されます。
*
* @param string $description 最大80文字のテキストです。
*
* @return void
*/
public function setDescription($description)
{
// ここにDocブロックは書けません
$this->description = $description;
}
}
|
Another example is to document the variable in a foreach explicitly; many IDEs use this information to help you with auto-completion:
以下の例では、foreachの中の変数を文書にします。多くのIDEは自動補完の補助としてこの情報を利用します。
1 2 3 4 5 6 | /** @var \Sqlite3 $sqlite */
foreach($connections as $sqlite) {
// there should be no docblock here
$sqlite->open('/my/database/path');
<...>
}
|
This is a generic name for anything that can be returned or provided as identity for a value.
It is recommended to read the chapter 型の定義 for a detailed description.
Each documentable element can be referenced using a unique name based on its local name and any containers it is in.
It is best demonstrated using an example:
\My\Space\MyClass::myMethod()
This FQSEN identifies the myMethod method that is contained in the MyClass class, which in turn is contained inside the My\Space namespace.
Sometimes called a short description, provides a brief introduction into the function of the associated element.
「短い説明文」とも呼ばれ、函数または関連する要素の要約した紹介を書きます。
A Summary ends in one of these situations:
サマリの終端は以下のいづれかの場合です：
A dot is following by a line break, or
行の最後がドットで終る、または
Two subsequent line breaks are encountered.
二つの連続した改行があるとき。
Some tags can also be used within text such as descriptions, such as the @link tag. Inline tags are surrounded by braces to set them apart from the surrounding text.
@link など、いくつかのタグは説明文といったテキストの中にタグを使用できます。インラインタグは周囲と分離するため、波括弧 {} で括ります。
An annotation is a specialized form of tag, that not only documents a specific aspect of the associated element, but also influences the way the application behaves. Specific functionality depends on the library that is using them, for instance in Doctrine you can specify that a class represents a database entity as follows:
アノテーションは特別な形式のタグで、関連要素の仕様を文書化するのみならず、アプリケーションの振舞に影響をもたらします。機能の仕様は利用するライブラリに依存しますが、Doctrineのインスタンスは次のようにデータベースのエンティティを記述できます。
1 2 3 | /**
* @ORM\Entity(repositoryClass="MyProject\UserRepository")
*/
|
For more on annotations, see Rafael Dohms’ video presentation or slides on annotations.
ほかのアノテーションについてはRafael Dohmsの video presentation または slides をご覧ください。
A Service Provider is part of the Plugin system for phpDocumentor. Each plugin must have a Service Provider class that will bind the classes necessary for that plugin into the Dependency Injection Container or one of it services.
The Service Provider is a concept coming from Pimple, the dependency injection container powering phpDocumentor.