< Unit Tests

Logging and Debugging >

## 8. Code Documentation

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

## 8.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`.

## 8.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.

### 8.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.

### 8.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:$ (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.

### 8.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:$
     */

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