CartoWeb code documentation is generated using PhpDocumentor, a JavaDoc-style doc generator. CartoWeb already includes version 1.3.0rc3 of PhpDocumentor.
Documentation is generated using script
makedoc.php
:
cd scripts php makedoc.php
This will generate documentation in directory
CARTOWEB_HOME/documentation/apidoc
.
DocBlocks are comments located at the beginning of a file, or just before a class, a method, a function outside a class or a variable declaration. These comments will be parsed by PhpDocumentor to generate documentation.
For a full description of DocBlocks, see official PhpDocumentor documentation.
In CartoWeb we use:
- Page-level DocBlocks: one DocBlock for each PHP file.
- Class, method, class variable and function (outside a class) DocBlocks: one DocBlock for each.
- Require, include, define: if needed, one DocBlock for each or all.
- Short description: if needed, a one line description.
- Long description: if needed, a longer description.
- @package <package> (file, class): we use one package for each directory which contains PHP files, it means there are the following packages: Client, Server, Common, CorePlugins, Plugins, Scripts, Tests.
- @author <author> (file): author with email address.
- @version $Id:$ (file): always '$Id:$', content automatically set by CVS.
- @param <type> [<description>] (method): type mandatory, description if needed.
- @return <type> [<description>] (method): type mandatory, description if needed.
- @var <type> [<description>] (variable): type mandatory, description if needed.
- {@link [<class>|<method>]} (anywhere): to add a hyperlink to a class or method.
- @see [<class>|<method>] (anywhere): to add a reference to a class or method. @see is also used for interface implementation: Because PhpDocumentor doesn't inherit tags @param, @return, etc. and because we don't want to copy/paste these tags, we add a simple @see tag to interface method definition. See example below.
Here is a code example. Please note:
- $simpleVariable doesn't need a description, but @var tag is mandatory.
- here constructor doesn't need a description.
- getters and setters are too simple to have a description, but don't forget the @param and @return!
- use (but not abuse) of {@link} and @see. This can be really useful to navigate through documentation.
<?php /** * Test file * * The purpose of this file is to show an example of how to use * PhpDocumentor DocBlocks in CartoWeb. * @package MyPackage * @author Gustave Dupond <gustave.dupond@camptocamp.com> * @version $Id:$ */ /** * This is a require description */ require_once('required_file.php'); /** * This is a short description of MyClass * * MyClass long descrition. * @package MyPackage */ class MyClass extends MySuperClass { /** * @var int */ public $simpleVariable; /** * @var MyVarClass */ public $simpleObjectVariable; /** * This variable needs a description * @var string */ public $notSoSimpleVariable; /** * @param int */ function __construct($initialValue) { parent::__construct(); $this->simpleVariable = $initialValue; $this->simpleObjectVariable = NULL; $this->notSoSimpleVariable = ''; } /** * @param int */ function setSimpleVariable($newValue) { $this->simpleVariable = $newValue; } /** * @return int */ function getSimpleVariable() { return $this->simpleVariable; } /** * This is a short description for method * * This is a longer description. Don't forget to have a * look here {@link MyLinkClass::myLinkMethod()}. blah blah. * @param string description of first parameter * @param MyParamClass description of second parameter * @return boolean true if everything's fine * @see MyInterestingClass */ function myMethod($myFirstParameter, $mySecondParameter) { // blah blah return true; } /** * @see MyInterface::myImplementingMethod() */ function myImplementingMethod($myParameter) { // blah blah return true; } function myOverridingMethod($myParameter) { // blah blah return true; } } ?>