#### 结构元素
Structural Elements
> This is a collection of Programming Constructs which SHOULD be preceded by a DocBlock. The collection contains the following constructs:
* file
* require(_once)
* include(_once)
* class
* interface
* trait
* function (including methods)
* property
* constant
It is RECOMMENDED to precede Structural Elements with a DocBlock at its definition and not with each individual usage.
Example:
~~~
/** @var int This is a counter. */
$int = 0;
// there should be no docblock here
$int++;
~~~
Or:
~~~
/**
* 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;
}
}
~~~
Another example is to document the variable in a foreach explicitly; many IDEs use this information to help you with auto-completion:
~~~
/** @var \Sqlite3 $sqlite */
foreach($connections as $sqlite) {
// there should be no docblock here
$sqlite->open('/my/database/path');
<...>
}
~~~
