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;
}
}
?>
