<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
  <!ENTITY % cartoweb SYSTEM "../cartoweb.ent" >
  %cartoweb;
]>

<!-- $Id: code_documentation.xml,v 1.8 2005-11-09 14:29:31 fredj Exp $ -->

<chapter id="dev.code_documentation">
 <title>Code Documentation</title>

  <para> &cartoweb; code documentation is generated using <ulink 
    url="http://www.phpdoc.org/">PhpDocumentor</ulink>, a JavaDoc-style doc 
    generator. &cartoweb; already includes version 1.3.0rc3 of PhpDocumentor. 
    </para>
  
  <sect1 id="dev.code_documentation.generating"> 
  <title>Generating Documentation</title>
    <para> Documentation is generated using script 
      <filename>makedoc.php</filename>: 
        <screen><![CDATA[cd scripts
php makedoc.php]]></screen>
        This will generate documentation in directory 
      <filename>CARTOWEB_HOME/documentation/apidoc</filename>. </para>
 </sect1>

  <sect1 id="dev.code_documentation.docblocks">
    <title>DocBlocks</title>
    <para> 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. </para>
    <para> For a full description of DocBlocks, see <ulink 
      url="http://phpdoc.org/docs/HTMLSmartyConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.docblock">official 
      PhpDocumentor documentation</ulink>. </para>
    <sect2 id="dev.code_documentation.docblocks.types">
      <title>DocBlocks Types</title>
      <para> In &cartoweb; we use:
        <itemizedlist>
          <listitem>
            <para>Page-level DocBlocks: one DocBlock for each PHP file.
              </para>
          </listitem>
          <listitem>
            <para>Class, method, class variable and function (outside a class)
              DocBlocks: one DocBlock for each. </para> 
          </listitem>
          <listitem>
            <para> Require, include, define: if needed, one DocBlock for
              each or all.</para>
          </listitem>
        </itemizedlist>
      </para>
    </sect2>
    <sect2 id="dev.code_documentation.docblocks.content">
      <title>DocBlocks Contents</title>
      <para>
        <itemizedlist> 
          <listitem>
            <para> Short description: if needed, a one line description. 
              </para>
          </listitem>
          <listitem>
            <para> Long description: if needed, a longer description. </para>
          </listitem>
        </itemizedlist>
      </para>
      <para>
        <itemizedlist>
          <listitem> 
            <para> @package &lt;package&gt; (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. </para>
          </listitem>
          <listitem>
            <para> @author &lt;author&gt; (file): author with email address.
              </para>
          </listitem>
          <listitem>
            <para> @version &dollar;Id:&dollar; (file): always
              '&dollar;Id:&dollar;', content automatically set by CVS. </para>
          </listitem>
          <listitem>
            <para> @param &lt;type&gt; [&lt;description&gt;] (method): type
              mandatory, description if needed. </para>
          </listitem>
          <listitem>
            <para> @return &lt;type&gt; [&lt;description&gt;] (method): type
              mandatory, description if needed. </para>
          </listitem>
          <listitem>
            <para> @var &lt;type&gt; [&lt;description&gt;] (variable): type
              mandatory, description if needed. </para>
          </listitem>
          <listitem>
            <para> {@link [&lt;class&gt;|&lt;method&gt;]} (anywhere): to add
              a hyperlink to a class or method. </para>
          </listitem>
          <listitem>
            <para> @see [&lt;class&gt;|&lt;method&gt;] (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. </para>
          </listitem> 
        </itemizedlist>
      </para>
    </sect2>
    <sect2 id="dev.code_documentation.docblocks.example">
      <title>Example</title>    
      <para>Here is a code example. Please note:
      <itemizedlist>
        <listitem>
          <para> $simpleVariable doesn't need a description, but @var tag is
            mandatory. </para> 
        </listitem>
        <listitem>
          <para> here constructor doesn't need a description. </para>
        </listitem>
        <listitem>
          <para> getters and setters are too simple to have a description, but
            don't forget the @param and @return! </para>
        </listitem>
        <listitem>
          <para> use (but not abuse) of {@link} and @see. This can be really
            useful to navigate through documentation. </para>
        </listitem>
      </itemizedlist>
    </para>
    <para>
      <programlisting><![CDATA[<?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 ]]>&dollar;Id:&dollar;<![CDATA[
 */

/**
 * 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;
        } 
}
?>]]></programlisting>
    </para>
    </sect2>
  </sect1>

</chapter>
