Générer de la documentation pour PHP
La documentation relative à un ensemble de classes dans un langage de programmation est très importante car elle permet à d’autres personnes de comprendre rapidement l’architecture de votre application sans avoir à parcourir tous les fichiers. C’est un gain de temps appréciable !
Cette documentation peut également vous être utile, si vous abandonnez le développement d’un projet pendant quelques temps et que vous souhaitez vous y replonger.
Heureusement des outils existent pour générer automatiquement de la documentation. Un ensemble de paramètres est à inscrire dans votre code, l’outils de documentation récupérera ces éléments pour générer un document en HTML, PDF, etc…
Les principaux paramètres sont regroupés dans ce document. Voici un exemple :
/**
* Instantiate a new user
* @param int $id
* @access public
*/Ici on dit par exemple que ce qui va suivre aura la description “Instantiate a new user”, prendra en paramètre un int de nom $id et aura un accès public. Ce code est à placer avant une déclaration de méthode par exemple.
Pour générer la documentation, mon choix s’est porté sur PHPDocumentator, qui semble après mes tests le plus complet.
Voici le processus :
- Télécharger le script sur http://www.phpdoc.org/
- Mettez le dossier téléchargé sur votre serveur web
- Remplissez l’onglet “Files” afin de définir les fichiers et dossiers à analyser
- Remplissez le dossier cible (où sera la documentation) dans l’onglet “Output”
- Renseignez les champs dans l’onglet “Options” si vous le souhaitez
- Cliquez sur “Create” en bas à droite de la page
- Rendez-vous dans le dossier spécifié précédemment dans “Target”
- Ouvrez la page index.html
Comme vous pouvez le voir la génération est simple. En revanche j’ai rencontré un petit problème avec les fichiers .css générés dans le dossier /media du dossier “Target”. Les fichiers sont en .cs et non en .css, modifiez juste l’extension pour que tout rentre dans l’ordre.