Code Documentation

From Cloudrexx Development Wiki
Jump to: navigation, search

Introduction

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.

Guidelines

  1. First, Study the introduction Your First Set of Documentation
  2. Then use at least the mandatory Tags as listed below to properly document the code

Example

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   CONTREXX CMS - Comvation AG Thun
 * @author      Robin Glauser <robin.glauser@comvation.com>
 * @package     contrexx
 * @subpackage  coremodule_access
 * @version     1.0.0
 */

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

  • 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)