©
. Document créé le 17 avril 2011 , mis à jour le 17 avril 2011.Une personne qui n'a jamais commis d'erreurs n'a jamais tenté d'innover. Albert Einstein
Accueil du site > Astuces > PHP > Construire la documentation d’une application PHP
Construire la documentation d’une application PHP automatiquement est à la portée de quelques clics, à condition bien sûr que ledit code PHP soit proprement commenté.
Un commentaire reconnu par PhpDocumentor est du style commentaire pour le langage C. Le tag d’ouverture doit contenir 2 astérisques :
<?php/**
* Ce commentaire concerne le fichier PHP
* car il est le premier commentaire.
* Il sera affiché dans la documentation
*/
/**
* Ce commentaire concerne la fonction foo()
* Il sera affiché dans la documentation concernant cette fonction.
* Il précisera le type de résultat retourné.
* @return int|string un entier ou une chaîne
*/
function foo ($mixed) {
return ($mixed);
}
?>
Ce qui donnera en version web au format HTML:Smarty:HandS :
On parle là de PHPDoc ou DocBlock.
Il est possible de décrire un fichier, une fonction, une globale, une classe, etc. Si besoin, consulter le manuel PhpDoc phpDocumentor Guide to Creating Fantastic Documentation.
PhpDocumentor propose même plusieurs formats de documentation : site HTML du style de la documentation en ligne de php.net ; un fichier CHM ; PDF.
Etrangement, les modèles, appelés template, fournis, ont parfois le suffixe tp au lieu de tpl. Ce qui génère de nombreuses erreurs du type :
PHP Warning: Smarty error: unable to read resource: "pkgelementindex.tpl" in...
Pour s’en débarrasser, il suffit de compléter le suffixe des fichiers tp.
Aller dans le dossier installé, puis dans le dossier phpDocumentor/Converters :
cd phpDocumentor/Converters
Renommer tous les suffixes des fichiers tp en tpl, via une petite boucle du style :
for f in `find . -name '*.tp'`; do mv "${f}" "${f}l"; done
A voir également, les fichiers images avec extension .pn au lieu de .png.
for f in `find . -name '*.pn'`; do mv "${f}" "${f}g"; done
et css
for f in `find . -name '*.cs'`; do mv "${f}" "${f}s"; done
Patienter. Patienter. C’est parfois long. Et parfois ça ne fonctionne pas, en général pour manque de mémoire allouée à PHP. Dans ce dernier cas, corriger la variable memory_limit de votre fichier php.ini.
En option, vous pouvez demander la recopie dans cette documentation des sources en mode colorisé via l’option Generate Highlighted Source Code du menu Options. Attention, les sources sont enrichis de code HTML verbeux qui multiplie la taille originale par 5, en moyenne.
Sauf usage de Files to ignore du menu Files, tous les fichiers ayant un des suffixes (extension) suivants seront analysés :
Ce sont ces types de fichier qui sont analysés par PhpDocumentor. Les autres types de fichier sont ignorés.
Pour ajouter d’autres extensions de fichier, compléter la constante de configuration _phpDocumentor_phpfile_exts du fichier phpDocumentor.ini.
Que l’on trouve dans le menu Output, HTML avec frames, sans frames (Smarty), et les formats PDF, CHM, ...
Démonstration des formats sur http://manual.phpdoc.org/
A voir éventuellement :
Plus rapide, mais nécessite la connaissance du terminal, du shell.
Là aussi, parfois, ça ne fonctionne pas, en général pour manque de mémoire allouée à PHP. Dans ce dernier cas, corriger la variable memory_limit de votre fichier php.ini. Il est possible également de redéfinir cette valeur dans le script PHP phpdoc en insérant - par exemple - en début de script (aprés < ?php) ini_set(‘memory_limit’,’512M’) ; pour 512 Mo.
Exemple :
./phpdoc --directory /usr/local/sources \
--target /usr/local/docs
En plus simple :
./phpdoc -d /usr/local/sources -t /usr/local/docs
Les forums sont fermés.