PHP Documentor
A DocBlock looks like this:
/**
* A summary informing the user what the associated element does.
*
* A *description*, that can span multiple lines, to go _in-depth_ into the details of this element
* and to provide some background information or textual references.
*
* @param string $myArgument With a *description* of this argument, these may also
* span multiple lines.
*
* @return void
*/
function myFunction($myArgument)
{
}
Please see the tag reference for the canonical list of tags and their complete descriptions.
Annotations
In addition to the above you might also encounter Annotations when viewing DocBlocks. An Annotationis a specialized form of tag that not only documents a specific aspect of the associated element but also influences the way the application behaves.
Annotations come in various forms, many look exactly like normal tags but some have a more complicated syntax:
/**
* @ORMEntity(repositoryClass="MyProjectUserRepository")
*/
In the example above we demonstrate how you define that a class represents a database entity in Doctrine; as you can see the tag name is separated into two parts, a namespace and the actual annotation name,
| Tag | Element | Description |
|---|---|---|
| api | Methods | declares that elements are suitable for consumption by third parties. |
| author | Any | documents the author of the associated element. |
| category | File, Class | groups a series of packages together. |
| copyright | Any | documents the copyright information for the associated element. |
| deprecated | Any | indicates that the associated element is deprecated and can be removed in a future version. |
| example | Any | shows the code of a specified example file or, optionally, just a portion of it. |
| filesource | File | includes the source of the current file for use in the output. |
| global | Variable | informs phpDocumentor of a global variable or its usage. |
| ignore | Any | tells phpDocumentor that the associated element is not to be included in the documentation. |
| internal | Any | denotes that the associated elements is internal to this application or library and hides it by default. |
| license | File, Class | indicates which license is applicable for the associated element. |
| link | Any | indicates a relation between the associated element and a page of a website. |
| method | Class | allows a class to know which ‘magic’ methods are callable. |
| package | File, Class | categorizes the associated element into a logical grouping or subdivision. |
| param | Method, Function | documents a single argument of a function or method. |
| property | Class | allows a class to know which ‘magic’ properties are present. |
| property-read | Class | allows a class to know which ‘magic’ properties are present that are read-only. |
| property-write | Class | allows a class to know which ‘magic’ properties are present that are write-only. |
| return | Method, Function | documents the return value of functions or methods. |
| see | Any | indicates a reference from the associated element to a website or other elements. |
| since | Any | indicates at which version the associated element became available. |
| source | Any, except File | shows the source code of the associated element. |
| subpackage | File, Class | categorizes the associated element into a logical grouping or subdivision. |
| throws | Method, Function | indicates whether the associated element could throw a specific type of exception. |
| todo | Any | indicates whether any development activity should still be executed on the associated element. |
| uses | Any | indicates a reference to (and from) a single associated element. |
| var | Properties | |
| version | Any | indicates the current version of Structural Elements. |