Dans n’importe quel projet, la documentation est presque indispensable dans la mesure où l’on passe plus de temps à relire et à maintenir du code qu’a en écrire… Commenter le code source est tout aussi important et permet d’intervenir beaucoup plus rapidement sur le code, même après quelques mois voir années. Il permet aussi à quelqu’un qui reprend le projet de mieux comprendre comment il fonctionne.

Seulement, une fois que l’on a commenter, on doit à nouveau s’occuper d’écrire la documentation, chose très ennuyante. Afin d’aider au maximum les développeurs, il existe de nombreux outils pour créer des documentations à partir du code source comme PHPDocumentor.

PHP Documentor

PHP Documentor est un outil permettant de créer très simplement une documentation à partir d’un projet/dossier/fichier une documentation très complète, si votre projet est très bien commenté. Pour créer une documentation, vous pouvez utiliser PHP Documentor en console ou grâce à l’interface Web “Doc Builder”. C’est cette dernière que nous allons utiliser…

Créer votre documentation

Accèdez au répertoire /docbuilder de PHP Documentor via votre navigateur (en passant par un serveur avec PHP bien entendu). Vous devez arriver sur une page comme ceci:

A – Menu horizontal permettant de choisir toutes les options
B – Répertoire de travail, c’est-à-dire le répertoire que PHP Documentor va utiliser pour créer ses fichiers temporaires.
C – Boutons de création
D – Console, endroit dans lequel les informations d’éxécution seront affichées si vous ne choisissez pas d’éxécuter dans une nouvelle page.

Onglet “Config”

Dans l’onglet Config, on peux choisir une configuration spéciale (fichiers inis) déjà préparée. Cette configuration inclue le répertoire source, le répertoire cible, les fichiers à parser, ceux à ne pas parser, etc… Tout est déjà préparer. Il vous suffit donc de créer ce fichier ini, de le séléctionner et d’appuyer sur le bouton “Create”. Nous l’allons pas les utiliser.

Onglet “Files”

Cet onglet est le plus important car il défini les fichiers/dossiers à – ne pas – parser. Il y a donc 3 champs de textes, dans lesquels vous devez mettre respectivement la liste des fichiers à analyser, la liste des dossiers à analyser et la liste des fichier à ne pas analyser.

Ces listes sont en fait des chemins locaux (ex: /home/samuel/projet1/fichier.php ou d:/samuel/projet1/fichier.php) séparés par des virgules. Les wildcards “*” et “?” sont autorisés.

Onglet “Output”

Il défini dans quel endroit et sous quelle forme vous voulez que vos documentations soient exportées. Le champ “Target” défini l’endroit où la documentation doit être exportée et le champ “Output format” le format dans lequel doit-être exporté la documentation. Vous pouvez mettre ces valeurs:

• HTML:frames:default, le modèle par défault
• HTML:frames:d-sites, le modèle D-Sites, si vous l’avez télécharger. Voir plus bas.
• XML:DocBook/peardoc2:default, pour en faire des fichiers XML
• PDF:default:default, pour en faire du PDF
• CHM:default:default, pour en faire un fichier d’aide (Windows) compilé.

Note: Le menu déroulant sous le champ “Output format” permet de sélectionner un modèle et de voir à quoi il ressemble via une petite icone.

Onglet “Options”

Dans cet onglet, vous pouvez changer le nom de la documentation (Generated Documentation Title), les noms par défaut des packages et catégories.

Vous pouvez ajouter des tags, ils sont présents dans les commentaires et commencent par un “@”, comme “@author” ou “@access”. Ils permettent d’ajouter des informations supplémentaires mais bien précises (un ou deux mots, pas plus) concernant l’objet commenté. Si vous en utilisez qui ne sont pas “classiques”, vous pouvez ajouter une liste de tags séparés par des virgules.

Le champ “parse @access private” est à cocher si vous souhaitez voir présent les méthodes privées de votre code. Si vous cochez la case, vous ne verrez pas la différence entre les méthodes/variables publiques et privées sauf si vous utilisez le modèle D-Sites.

Le style utilisé sur D-Sites

Les documentations des librairies de D-Sites sont créés avec PHP Documentator, avec un modèle particulier (français et définition des accès des méthodes/variables).

1. Télécharger le template PHP Documentor au format zip
2. Télécharger le template PHP Documentor au format tar.gz

Le dossier “d-sites” de l’archive est à mettre dans le dossier /phpDocumentor/Converters/HTML/frames/templates de PHPDocumentor.