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:
/**
ma documentation
*/
?>
Le /** de début de commentaire est important, c'est lui qui défini 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 :
/**
@class maClasse
*/
/** @doc
Texte de documentation
*/
/**
@function maFonction
*/
?>
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 :
@param <type> <nom> <description> (<valeur par défaut>)
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 :
@return <type>
Reste du bloc
Tout ce qui est dans le bloc est 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
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;
}
}
}
?>