fr en

Générer de la documentation pour PHP

2009-10-10 2 Min. lecture Développement Web PHP Aymeric

phpdoc

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.