PHP Code Documentation
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.
- First, Study the introduction Your First Set of Documentation
- Then use at least the mandatory Tags as listed below to properly document the code
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 <email@example.com> * @package cloudrexx * @subpackage coremodule_access */
- 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)
- @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)