PHPDoc is an adapted Javadoc documentation standard for use in PHP . While the commenting standard has only a formal status, however, it is planned to consolidate it as one of the development standards for PHP frameworks developed by the PHP-FIG group. The prepared standard will receive the number PSR-5 [1] . PHPDoc supports both object-oriented and procedural code in documents.
To interpret the code, a separate phpDocumentor program has been created .
Content
- 1 PHPDoc Components
- 1.1 Doc blocks
- 2 Application
- 3 References
- 4 notes
PHPDoc Components
Doc Blocks
Doc blocks ( DocBlock comments ) are multiline C -style comments placed in front of the document element. The first character in the comment (and at the beginning of the comment lines) must be * . Blocks are separated by blank lines.
Example Doc block for foo () function:
/ **
* @param string $ msg string to output
* @author WikiEditor
* @copyright 2016 Wikipedia
* @return string unchanged
* /
function foo ( $ msg = '' ) {
return $ msg ;
}
Application
When developing your large projects, all the subtleties of which cannot be kept in mind, just like when refining other people's projects, you often have to peek into the previously written code. This allows you to more accurately imagine the returned, created objects and what you can do with them. Given that there is implicit type conversion in PHP, errors are potentially possible when operations are performed on objects of different types. In languages ββwith strong typing, this will not happen - the program simply does not compile.
To avoid this, they use PHPDoc and other similar technologies. Suppose there is a code :
...
$ eventData = new EventData ();
$ eventData -> sender = $ controller ;
$ eventData -> name = 'onDelete' ;
$ eventData -> group = 'global' ;
$ eventData -> arguments = array ( 'id' => 15 );
$ eventDispatcher -> triggerEvent ( $ eventData );
...
A third-party developer, while reading this code, may not know what $ controller contains, but the IDE will tell him if it supports PHPDoc. That is, by typing: $eventData->controller-> - we can see what is inside the attribute named controller. As a result, there is no need to go into the jungle of code to find out what is transmitted by this object and in what type.
Links
- http://www.phpdoc.org/ - project site
- One example of application on the site Habrahabr.