Documenter correctement son code avec PhpDocumentor
PhpDocumentor permet de générer automatiquement la documentation d'une application PHP, au format HTML ou PDF, à partir des commentaires inclus dans les différents fichiers .php
PhpDocumentor s'installe grâce à Pear. Sur Ubuntu, il suffit donc de :
sudo pear install PhpDocumentor
Pour générer la documentation d'une application, il suffit de taper :
phpdoc -o HTML:Smarty:PHP -d /mon/application/php -t phpdocumentor
où :
- -o indique le format du rapport (dans ce cas-ci HTML, mais PDF est également possible);
- -d est le répertoire où se trouve le code à analyser et documenter;
- -t indiquer dans quel répertoire il faut enregistrer la documentation.
Pour pouvoir être analysés correctement par PhpDocumentor, les commentaires doivent être rédigés d'une façon bien précise : chaque élément (fichier, classe, fonction, variable,...) doit être précédé par un "docblock" de la forme suivante :
/**
* Description courte
*
* Description longue
* (sur plusieurs lignes)
*
* @tags
*/
Il existe toute une série de tags reconnus par PhpDocumentor. La liste complète est naturellement disponible sur le site de PhpDocumentor. Les tags les plus courants sont présentés dans l'exemple ci-dessous, qui a d'ailleurs servi à générer la documentation visible ci-dessus.
<?php
/**
* Description courte du fichier
*
* Description longue du fichier...
*
* PHP version 5
*
* @category Catérogie
* @package None
* @author Thibault Debatty <thibault.debatty@gmail.com>
* @copyright 2011 Thibault Debatty
* @license http://www.php.net/license/3_01.txt PHP License 3.01
* @link http://www.mon-application.be
*/
/**
* Description courte de ma fonction
*
* @param my_class $param1 Description de param1
* @param <type> $param2 Description de param2
*
* @return <type>
*/
function myFunction(my_class $param1, $param2)
{
return $param1->method($param2);
}
/**
* Description courte de ma classe (une seule ligne)
*
* Description longue (plusieurs lignes) de ma classe
* - Point 1
* - Point 2
*
* @category Catérogie
* @package None
* @author Thibault Debatty <thibault.debatty@gmail.com>
* @license http://www.php.net/license/3_01.txt PHP License 3.01
* @link http://www.mon-application.be
*/
class MyClass
{
/**
*
* @var <type>
*/
public $attribute1;
/**
* Description de method
*
* @param <type> $param Description de param
*
* @return <type>
*/
public function method($param)
{
return "abc";
}
}
?>
Les commentaires ci-dessous ont été rédigés conformément au standard PEAR. Comme vous pouvez le constater :
- La description longue du fichier doit indiquer la version de PHP;
- Les descriptions qui suivent les différents @tags doivent toujours être alignées;
- Dans le Docblock d'un fichier, les tags @category, @package, @author, @copyright, @license et @link sont nécessaires, et dans cet ordre;
- Dans le Docblock d'une classe, les tags @category, @package, @author, @license et @link sont nécessaires (également dans cet ordre);
- Après le tag @author, il faut indiquer le nom et l'adresse e-mail de l'auteur;
- Après le tag @license, il faut indiquer l'adresse web et le nom de la license utilisée;
- Après le tag @copyright, il faut indiquer l'année et le nom du détenteur du copyright;
- Dans le Docblock d'une fonction ou d'une méthode, il faut laisser une ligne vide entre le dernier tag @param et le tag @return.
