====== Documentation du Code PHP ======

Dotclear utilise un format assez proche de PHPDoc pour documenter le code. La syntaxe est très simple.


===== Bloc de documentation du code =====

Pour ajouter la documentation d'un code, il suffit d'ouvrir un commentaire de la forme suivante:

<code php><?php
/**
ma documentation
*/
?></code>

Le code de début de commentaire est important, c'est lui qui définit le début du bloc de documentation.

===== Prototype =====

La prototype indique ce que l'on est en train de documenter. Les prototypes possibles sont les suivants :

    * @class <nom> : une classe
    * @function <nom> : une fonction ou une méthode
    * @doc : une documentation sans type 

Tout bloc de documentation doit avoir un prototype.

==== Exemples : ====

<code php><?php
/**
@class maClasse
*/

/** @doc
Texte de documentation
*/

/**
@function maFonction
*/
?></code>

===== Attributs =====

Selon le prototype, on peut ajouter des attributs au bloc de documentation. Un attribut commence par @ comme un prototype.

==== Paramètre ====

Il peut être ajouté à une classe ou à une fonction. Syntaxe :

<code php>@param <type> <nom> <description> (<valeur par défaut>)</code>

La valeur par défaut est facultative et doit toujours être entre parenthèses.

==== Valeur de retour ====

Cet attribut peut être ajouté uniquement à une fonction. Syntaxe :

<code php>@return <type></code>

==== Reste du bloc ====

Tout ce qui est dans le bloc et ne commençant pas par un @ sera interprété comme du texte de documentation. Le texte de documentation doit être écrit dans la syntaxe wiki de Trac.

=== Exemple ===

<code php><?php
class maClasse
{
        /** @doc
        === Un titre === */
        
        var $variable;
        
        /**
        @class maClasse
        
        @param integer variable Variable quelconque
        
        C'est une classe un peu '''inutile'''.
        */
        
        /**
        @function maFonction
        
        @param string           str     Une chaîne
        @param boolean          oui     Un booleen vrai par défaut (true)
        
        @return string
        
        Encore une fonction qui ne fait pas grand chose...
        */
        function maFonction($str,$oui=true)
        {
                if ($oui) {
                        return $str;
                } else {
                        return false;
                }
        }
}
?></code>