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
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.
/** * * @package MediaWiki * @subpackage SpecialPage */
These tags are standard phpDoc tags. Howevever, some are recents or less known. Your IDE (Integrated Developement Environment; editor) may eventually ignore them and will thus not highlight or suggest the tag. E.g. Zend Studio ignores * @uses.
/** * * @uses */
These tags can be used without any patch to phpDoc. They are usefull for human read of sources. To be really usefull, they sould 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
Non standard phpDoc
These tags would require a patched version of phpDoc.
Avoid.... Currently none...
docBlock and how to begin a file
The beginning of file looks like :
<? // !FILE : includes/SpecialPermissions.php /** * */
how to end a file
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 !!!