7. Code Documentation

CartoWeb code documentation is generated using PhpDocumentor, a JavaDoc-style doc generator. CartoWeb already includes version 1.3.0rc3 of PhpDocumentor.

7.1. Generating Documentation

Documentation is generated using script makedoc.php:

 
cd scripts
php ./makedoc.php
        

This will generate documentation in directory CARTOWEB_HOME/documentation/apidoc.

7.2. DocBlocks

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.

7.2.1. DocBlocks Types

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.

7.2.2. DocBlocks Contents

  • 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: dev.code_documentation.html,v 1.1 2005/11/10 12:21:33 sypasche Exp $ (file): always '$Id: dev.code_documentation.html,v 1.1 2005/11/10 12:21:33 sypasche Exp $', 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.

7.2.3. Example

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: dev.code_documentation.html,v 1.1 2005/11/10 12:21:33 sypasche Exp $
 */

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