Articles Tagués ‘phpdocumentor’


phpDocumentor est un générateur de documentation pour PHP et à pour fonction de créer une documentation de votre programme source « élément parfois négligé« . Pour y parvenir, il s’appuie sur les commentaires inclus à l’intérieur de votre code source. D’où l’importance de bien expliciter vos routines, fonctions et autres procédures.

Les caractéristiques principales de phpDocumentor sont :

  • Génération hors ligne
  • Génération en ligne
  • Templates personnalisables
  • guide, phpdoc
  • Formats de sortie en HTML, CHM, PDF, XML

Avoir recours à phpDocumentor vous permettra de pouvoir revenir sur un code après un long moment, de permettre à d’autres développeurs de voir en un clin d’oeil la structure de votre application et une meilleure maintenance du code.

phpDocumentor peut-être utilisée de deux manières : soit en mode graphique avec l’interface web, soit en ligne de commande.

Le site de phpDocumentor.

La documentation sur phpDocumentor.

Le téléchargement de phpDocumentor.

Installation rapide de PhpDocumentor :

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

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 à la page d’administration de PhpDocumentor.

En haut à gauche vous allez voir ce menu :

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 :

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é :

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

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 :

01
02
03
04
05
06
07
08
09
10
11
12
/**
* @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