PhpDoc
 | This page is outdated. |
phpDocumentor is a widely used, advanced but easy-to-use documentation generator for PHP code. Detailed commenting following a straight-forward ruleset in source code is converted into HTML docs by the application when a release of MediaWiki is made. A brief set of information on reasons why good documentation is considered important can be found here. This page aims to give a quick rundown of phpDoc's usage and syntax; it aims to give you just enough information to get phpDoc syntax into your next coding project. Extension information can be found in the documentation here.
Starting with a DocBlock[edit]
The syntax for phpDoc is easy to use. Modern IDEs often have support built in. Additionally, en:JavaDoc is considered to be very similar to it. There are however a lot of additional features and formatting tricks to make your documentation more effective.
A multi-line comment called a DocBlock is the base of phpDoc usage. It is the core element.
/** * A short description with no returns or ending with a period. * * Some extended information * @tags */
IMPORTANT: After the initial /*, you must insert another asterisk right after it. So the first line of a DocBlock must always be /**.
<important>ALSO IMPORTANT</important>: Every line you want PHPDoc to read, must start with an asterisk *. PHPDoc will ignore any lines that do not start with an asterisk.
NOT SO IMPORTANT, BUT FOR STYLE AND CONSISTENCY... after the DocBlock opener /** indent every line following it with once space, as above, and no extra return after the start of the docblock. Zend and Eclipse with PHPeclipse do this for you automatically.
Recommended Tags[edit]
Well known tags often used[edit]
/** * * @package MediaWiki * @subpackage SpecialPage */
Standard, but less common, phpDoc tags[edit]
These tags are standard phpDoc tags. However, some are recent or less known. Your IDE (Integrated Development Environment; editor) may eventually ignore them and will thus not highlight or suggest the tag. E.g. Zend Studio ignores * @uses.
/** * * @uses */
Customized phpDoc tags[edit]
These tags can be used without any patch to phpDoc. They are useful for human read of sources. To be really useful, they should be specified (as a comma separated list) when generating the doc.
/** * @copyleft * @requires */
Here is the comma separated list as it should be provided to phpDoc
copyleft,requires
Non standard phpDoc[edit]
These tags would require a patched version of phpDoc.
Avoid.... Currently none...
docBlock Templates[edit]
File[edit]
docBlock and how to begin a file[edit]
The beginning of file looks like :
<? // !FILE : includes/SpecialPermissions.php /** * */
how to end a file[edit]
There is no docBlock at the end of file. Any file should end with something like :
// !EOF : includes/SpecialPermissions.php ?>
The // !EOF : is usefull to make sure you got the last line when you read a printed listing. It is a haDoc convention usefull when hacker uses grep or similar tools to help understanding a software.
It's a small but common error to leave spaces and empty lines after the final ?>. This is generally without consequence, unless the file is intended to be included before sending HTTP headers, using cookies, managing sessions, etc.
!!! as a matter of principle, you should NEVER leave whitespaces after ?> even if you perfectly know that this very file will never be included before sending HTTP headers !!!