Documentation du Code PHP

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

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

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

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

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.

<?php
/**
@class maClasse
*/
 
/** @doc
Texte de documentation
*/
 
/**
@function maFonction
*/
?>

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

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

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

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

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

@return <type>

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.

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