PHPDoc
PHPDoc is a format for comments in PHP code based on Javadoc . It is used to document variables, functions, methods and classes in PHP source code in order to use this information to create documentation, e.g. on an HTML basis. The expression was created around 2000, when a documentation tool based on Javadoc was presented as part of a presentation, which is under the PHP license .
example
There is a fictitious method whose description, parameters and return value are to be defined:
/**
* Get all image nodes.
*
* @param \DOMNode $node The \DOMDocument instance
* @param boolean $strict If the document has to be valid
*
* @return \DOMNode
*/
public function getImageNodes(\DOMNode $node, $strict = true)
{
// ...
}
The information enclosed in asterisks for the description of the method parameters is typical for PHPDoc comments and must consist of this formatting. In the example, @paramthe two function parameters are defined with the help of (in the order data type , variable name , brief explanation ), and the return data type is also specified.
Use
Using the descriptions, e.g. for a method, a PHPDoc parser can generate API documentation that clearly explains the required function parameters. Another advantage is that development environments record these comments and thus perform code completion. They also warn of this if, for example, an object type is passed that does not match the specification of the PHPDoc comment.
See also
- phpDocumentor uses the format
- Javadoc