NetBeans, docBlocks et ApiGen

On le dit et le répète, il est important de documenter ses sources. Car d’ici quelques mois, on ne saura pas à quoi sert une fonction, ou quels paramètres il faut lui envoyer… Et à fortiori si on travaille à plusieurs, ou si on utilise du code trouvé sur Internet (voire si on le distribue nous même).

Commenter c’est bien, bien commenter c’est encore mieux.

C’est là qu’interviennent les docBlocks, ApiGen et autre fantaisies qui simplifient la vie.

Syntaxe des commentaires: DocBlock

Pour pouvoir pleinement bénéficier des commentaires, il convient d’avoir une syntaxe rigoureuse, et tant qu’à faire normalisée, JavaDoc (et PhpDoc, son adaptation à php). Les deux utilisent un système de bloc de documentation, appelé docBlock…

Le DocBlock sera précisé en début de bloc, c’est à dire avant une déclaration de fonction, de classe, etc.

Le bloc va commencer par /**, chaque ligne qui suit sera précédée d’une étoile de commentaire, et le tout se terminera par */ tout ceci non pas pour être joli bien sûr.

 /**
 * Calcul du périmètre d'un cercle
 *
 * @author Richard Carlier
 * @version 1.0.0
 * 
 * @param  real $diametre    Le diamètre du cercle
 * @return real périmètre calculé
 */
function calculerPerimetreCercle ( $diametre ) {
    // @todo - un truc restant a faire ?
    return $diametre * pi();    
}

La première lignes (ou les) seront les explications du rôle de la fonction (ou de la méthode…). Suivent alors les tags (noms des auteurs, numéros de version… liste complète sur le site phpDoc).

Suivront la liste des paramètres, en 4 parties (séparées par des espaces ou tabulations).

* @param type $variable Lorem Ipsum

Explications:

• @param, qui est le tag signifiant que la chose est un paramètre…
• type c’est à dire le type de la donnée (int, real, string, array…) ou bien sûr un type d’objet…
• $variable, le nom de la variable
• Lorem Ipsum, c’est à dire les explications de ce que est censée contenir la variable en question

Sur le même principe, la valeur de retour (avec le type et quelques explications…) ; ou @return null (ou @return void) si la fonction ne retourne rien…

 * @return real périmètre calculé

Certes, mon exemple est simpliste, on se doute qu’une fonction qui s’appelle calculerPerimetreCercle et qui prend comme paramètre un $diametre… Mais même documentée, vos fonctions, variables et autres classes doivent être correctement nommées (la doc allant avec pourra alors être allégée.

On peut retrouver également des DocBlocks linéaire, c’est à dire sur une seule ligne.

    // @todo - un truc restant a faire ?

ou

    /* @todo - un truc restant a faire ? */

Ok, mais à quoi ça sert d’être aussi rigoureux ?

Bénéfice direct dans NetBeans

En commençant à taper la fonction, ou au survol (en appuyant sur Ctrl) vient apparaître une belle bulle d’aide:

A noter qu’Eclipse utilisera également ces informations.

Vous avez ainsi toutes les explications nécessaires… Au passage

• Ctr-Shift-Space si la fonction est déjà tapée, la fenêtre se réouvre
• un contrôle click sur le nom de la fonction  vous emmène directement vers le code d’icelle!
• Notons aussi que les tags @todo nous permettent de voir ce qu’il reste à faire.
  Allez dans Windows > Actions Items (qui fera également ressortir toutes les erreurs ou avertissements du projet)

Installation de API Gen

Avant de continuer, il convient d’installer ApiGen, un outil de documentation de votre code, retenu par NetBeans pour créer vos docs.

L’installation est très simple, il suffit de télécharger apigen (la version standalone) et de dézipper votre dossier apigen quelque part dans votre ordinateur. Je l’ai mis dans:

C:\wamp\tools\apigen

Configuration de NetBeans

Allez dans le menu Tools, puis Options. Sélectionnez l’icône PHP, et l’onglet ApiGen.

Il suffit de remplir l’adresse du script:

C:\wamp\tools\apigen\apigen.bat

et… c’est tout!

ApiGen en action

Si votre projet utilise la syntaxe phpDoc dont on vient de parler, ce qui va suivre est intéressant…

Un petit clic droit sur votre projet, et sélectionnez Generate Documentation.

On précise le répertoire de destination…

Et ne reste plus qu’à attendre… un certain temps (sans surprise, cela dépend de la taille de votre projet. Sur ma machine, documenter une installation de WordPress a pris le temps de faire la vaisselle et une poignée de niveaux d’Angry Birds… (oui, bon, je sais… ca vaut ce que ça vaut comme unités de mesures).

A l’arrivée, notre dossier est pleinement documenté.

C’est un véritable site html qui vient d’être créé, vous permettant de:

• naviguer dans la doc de chaque classe / fonctions
• voir l’arborescence des classes, et de leur héritage
• utiliser un moteur de recherche Javascript
• voir le code source avec colorisation syntaxique
• les problèmes (en rouge…)
• …

Bref, c’est là que la phrase documentez votre code prend tout son sens!