PhpDocumentor est une application qui sert à générer automatiquement une documentation php à partir des commentaires du code source. Nous allons apprendre à l’utiliser.

Installation rapide de PhpDocumentor :

Vous l’aurez deviné, il faut tout d’abord le télécharger C’est par ici.

php documentator

Une fois décompressé vous allez mettre votre dossier PhpDocumentor dans la racine de votre dossier www.

Bravo vous avez installé PhpDocumentor

Comme vous l’imagez PhpDocumentor met un certain temps pour générer toute la documentation d’une application php. Et apache par défaut limite le traitement du script php à 30 secondes. Ce qui bien évidement ne suffit pas pour faire tourner PhpDocumentor. Pour pallier ce problème il suffit de modifier fichier php.ini :

max_execution_time = 0;
max_input_time = 0;

Comme ça on est tranquille il n’y a plus de limite

Configuration de PhpDocumentator

Il faut se rendre sur cette adresse pour arriver la page d’administration de PhpDocumentor.

En haut à gauche vous allez voir ce menu :

PhpDocumentator

C’est l’onglet Files qui va nous intéresser.

Directory to parse : C’est le chemin du dossier où se situe votre application php (celui que phpDocumentor va traiter)

Files to ignore : On doit indiquer les types de fichier à ne pas traiter (ex : *.png, *.jpg, *.css)

Passons maintenant à l’onglet Output.

Target : Nous allons indiquer l’adresse où notre documentation va être générée ( ex: C:wampwwwdoc)

Output Format : C’est la forme que prendra votre doc (vous aurez le choix entre du xml , html ou pdf)

La dernière modification sera dans l’onglet Options.

Generated Documentation Title : C’est le nom de votre documentation.

Génération de la documentation

La c’est le plus simple on a juste à cliquer sur un bouton :

php documentor

La il faut attendre un peu que le script se génère. La durée est relative à la taille de votre application.

Si vous voyez ça, c’est que votre doc est bien généré :

PhpDocumentor

Oui, ma doc est bien formée, mais j’ai pratiquement pas d’information dessus.
Mais comment cela se fait-il Roul ???

Si vous avez une documentation appauvrie, c’est que vous avez mal commenté vos fonctions dans votre code source php.

Voici un exemple qui devrait faire une documentation assez complète :

/**
 * @author Roul
 * @access public
 * @param float $fNombre
 * @todo double le nombre entré en paramètre
 * @return float
 */

 public function double(float $fNombre)
 {
 	return $fNombre*2;
 }

Si vous voulez plus d’indications sur le formatage des commentaires je vous conseille de lire ceci

1. Alexandre Says:
   février 4th, 2009 at 11 h 54 min

   Il manque juste un exemple de document généré par ton script pour savoir si cela est intéressant ou non

2. roul Says:
   mars 28th, 2009 at 15 h 27 min

   Oui, très bonne remarque

   Je vais bientôt mettre un exemple concret.

3. Eupho Says:
   décembre 10th, 2009 at 12 h 24 min

   max_execution_time = 0; C’est pas très prudent, même en développement !

4. PhpDocumentor « The complete documentation solution for PHP » « CyberStudio Says:
   janvier 11th, 2010 at 12 h 41 min

   [...] PhpDocumentor est un outil puissant, largement répandu, afin de documenter son code PHP, voici un tuto afin de le mettre en place facilement. [...]

5. mrjay42 Says:
   mars 4th, 2010 at 17 h 00 min

   « max_execution_time = 0; C’est pas très prudent, même en développement ! »
   Là ce n’est pas gênant.
   Puisque le but n’est pas d’optimiser le script de PHPDoc’ on se doit de lui laisser tout le temps nécessaire.
   Le « max_execution_time = 0″ est justifié sur un projet conséquent, c’est sûr que pour un projet de taille réduite, c’est un peu démesuré.