18.PHPDocumentor

18.1.Introduction

Elément parfois négligé, la documentation du code généré est réellement un plus, souvent un gage de qualité. En PHP, nous disposons de la bibliothèque PhpDocumentor afin de générer une documentation basée sur les informations saisies au coeur même du code PHP.

18.2.Installation

PhpDocumentor fait partie de PEAR de l'annuaire pear.php.net. Pour l'installer il suffit donc de tapez la commande suivante

pear install PhpDocumentor

Vous devriez disposer d'une nouvelle commande phpdoc. Tapez donc

phpdoc --help

pour vous en assurer.

18.3.Utilisation

La première étape de la documentation du code consiste à ajouter des annotations via les commentaires entourant le code PHP, comme dans l'exemple suivant:

<?php
/**
 * Elève une valeur à la puissance 3
 * @param float $x valeur à mettre au cube
 * @return float
 */
function cube($x) {
     return $x*$x*$x;
}
?>

phpdoc_exemple.php

Lancez maintenant la commande

phpdoc -d doc -f phpdoc_exemple.php

et vous obtenez dans le répertoire doc/ (valeur précisée via le paramètre obligatoire -d), le résultat de la génération de la documentation du fichier spécifié par le paramètre -f. Le résultat de l'opération est (par défaut) un document HTML composé de frames que vous pouvez (déc)ouvrir avec votre navigateur en pointant sur le fichier doc/index.html.

Si vous avez réalisé votre test avec le fichier téléchargé sur notre site, alors peut-être avez constaté quelques problèmes avec les accents. Ceci vient tout simplement du fait que le template par défaut suppose que le fichier est encodé en ISO-8859-1 alors qu'il s'agit d'UTF-8. Vous n'avez qu'a forcer votre navigateur à un affichage en UTF-8 pour retrouver les accents.

18.4.Configuration des templates

PhpDocumentor propose différents templates (i.e. différentes façons de mettre en page la documentation). Vous avez vu la présentation par défaut mais si vous ajoutez l'option -o HTML:Smarty:PHP vous obtenez une présentation similaire à celle du site PHP. Essayez donc

phpdoc -d doc -o HTML:Smarty:PHP -f phpdoc_exemple.php

Il existe de nombreux templates proposés par défaut, dont voici les principaux:

HTML:default:default celui par défaut (avec frames)
HTML:Smarty:PHP présentation similaire à celle du site php.net
PDF:default:default version PDF

18.5.Utilisation dans la vraie vie

A titre d'exemple, nous avons fait nos tests de génération de documentation sur un unique fichier mais en pratique, c'est sur un ensemble de fichiers que vous aurez à le faire (les fichiers étant souvent liés entre eux. Ex: une classe peut hériter d'une autre déclarée dans un autre fichier). Aussi, vous serez plus probablement amené à utiliser l'option -d pour préciser le répertoire contenant l'ensemble des fichiers, plutot que -f.

phpdoc -d doc -o HTML:Smarty:PHP -d src