PHP Code Documentation

From Cloudrexx Development Wiki
Jump to: navigation, search


The API documentation of Contrexx is automatically generated based on its PHP source code using the documentation tool phpDocumentor 2. To ensure that the generation of the documentation works flawlessly, the whole source of Contrexx has to be documented properly. This is done using so-called DocBlocks.

Refer to the documentation of phpDocumentor 2 on how to properly document the PHP source code.

See also Wikipedia article about PHPDoc.


  1. First, Study the introduction What is a DocBlock?
  2. Then use at least the mandatory Tags as listed below to properly document the code
  3. Add useful (see Best practices for writing code comments) inline code documentation


Example docblock for class \Cx\Core_Modules\Access\Model\Event\AccessEventListener:

 * EventListener of component Access
 * This EventListener implements the registration of the media source provided by the Access component.
 * @copyright   CLOUDREXX - Cloudrexx AG
 * @author      John Doe <>
 * @package     cloudrexx
 * @subpackage  coremodule_access

Mandatory tags

File-level / namespace / class / interface / trait

property / constant

require(_once) / include(_once)
  • @ignore (as all classes should get loaded by the ClassLoader anyway)
    Note: Add comment about the specific reason why a require(_once) / include(_once) has been used

function (including methods)

Recommended / useful tags

  • @todo
  • @deprecated
  • @see
  • @uses
  • @since If the structural element is public, then use this tag to document the cloudrexx release since this feature became available
  • all other tags are nice to have and should be set where useful (for example author of a function if not the same as the author of the class)

Not used tags