PhpDoc

From Meta, a Wikimedia project coordination wiki
Jump to navigation Jump to search
Blue Glass Arrow.svg MediaWiki logo.png
This page should be moved to MediaWiki.org.
Please do not move the page by hand. It will be imported by a MediaWiki.org administrator with the full edit history. In the meantime, you may continue to edit the page as normal.

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. 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
 */

Customized phpDoc tags[edit]

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

 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 !!!

External links[edit]