Algorithmique & Programmation Orientée Objet Semestre 2 ST Commenter en javadoc
Introduction Le kit de développement Java comporte un utilitaire permettant de générer de la documentation pour un projet de développement à partir de commentaires placés et formatés directement au sein du code source. Cet utilitaire s'appelle javadoc. Cette documentation est générée sous la forme d'un ensemble de fichiers html et est donc affichable au moyen de tout navigateur internet. Parmi tous ces fichiers, celui qui renferme la homepage est nommé index.html. Il donne accès à tous les autres fichiers par l'intermédiaire de liens html. Javadoc permet de définir des commentaires qui viendront se placer en description: - d'un fichier, - d'une fonction, - d'un type agrégé, - d'un champ de type agrégé. Javadoc ne reprend pas les commentaires placés à l'intérieur des fonctions. Il n'est donc pas destiné à gérer ce type de commentaire, mais plutôt à générer des documents de référence contenant des documentations d'utilisation pour des constantes, des fonctions, des classes, des packages, des API, ... C'est au moyen de Javadoc qu'est créée la documentation de référence de l'API du langage Java. Utilisation Javadoc est un utilitaire exécutable en ligne de commande (au clavier dans une invite de commandes). Il s'appelle directement sur le(s) fichier(s) source .java à partir duquel(desquels) une documentation doit être réalisée. Exemples: javadoc MonApplication.java : Création de la documentation du fichier MonApplication.java. javadoc *.java : Création de la documentation de tous les fichiers dont l'extension est .java présents dans le répertoire implicite de lancement. Le lancement de javadoc a été paramétré sur les ordinateurs des salles de TP au sein de Scite pour répondre aux raccourcis clavier suivants: - Ctrl+0 : Exécution sur le fichier actif dans l'éditeur - Ctrl+1 : Exécution de la commande javadoc *.java Attention, la documentation ainsi générée est placée dans le répertoire qui contient les fichiers java traités. Formatage des commentaires Le code source suivant va servir d'exemple pour montrer les types de commentaires pouvant être créés. public class Exemple { final static double EPSILON = 0.00001; static class Position2D { double x = 0.0; double y = 0.0; }; static double [] initRandCroissant(int n) { int i; double [] tab = new double[n]; tab[0] = Math.random(); for ( i = 1 ; i < tab.length ; i = i+1 ) { tab[i] = tab[i-1]+Math.random(); } return tab; } static void affichageTableau(double [] t) { int i; for ( i = 0 ; i < t.length ; i = i+1 ) { Ecran.formater("%8.5f\n",t[i]); } } public static void main(String [] args) { Position2D pos = new Position2D(); Ecran.afficherln(EPSILON); Ecran.afficherln(pos.x," ",pos.y); affichageTableau(initRandCroissant(10)); } } Appliqué directement sur ce fichier source, javadoc donne le résultat suivant. La zone à onglets de gauche liste tous les fichiers et types agrégés qui ont été analysés et pour lesquels des fichiers de documentation ont été créés sous la forme de fichiers html. La zone de droite contient la description obtenue par clic sur un élément de la liste à onglets de gauche. Un seul fichier a été analysé, donc un seul onglet apparait à gauche pour lequel la description à droite fait apparaître une classe "Exemple" munie - dans la zone "Constructor Summary" d'un unique constructeur "Exemple()" (rôle non décrit ici), - dans la zone "Method Summary", d'une unique fonction (méthode): la fonction main d'entête public static void main(String [] args). Un clic souris sur l'un des constructeurs ou l'une des fonctions (méthodes) de ces listes donne accès dans le bas de la page web à une description plus détaillée du constructeur ou de la méthode. On constate que beaucoup d'items apparaissant dans le code source n'ont pas de description créée dans la documentation javadoc. Faire apparaître les items que l'on souhaite documenter L'utilitaire Javadoc, configuré comme il l'est, ne documente que les "choses" déclarées "public". Cela explique que la classe "Exemple" soit documentée ainsi que la fonction main, mais rien d'autre. Il convient de munir du mot réservé public les déclarations de tous les items que l'on souhaite faire apparaître: - fonctions - types agrégés - champs de type agrégé - constantes public class Exemple { public final static double EPSILON = 0.00001; public static class Position2D { public double x = 0.0; public double y = 0.0; }; public static double [] initRandCroissant(int n) { int i; double [] tab = new double[n]; tab[0] = Math.random(); for ( i = 1 ; i < tab.length ; i = i+1 ) { tab[i] = tab[i-1]+Math.random(); } return tab; } public static void affichageTableau(double [] t) { int i; for ( i = 0 ; i < t.length ; i = i+1 ) { Ecran.formater("%8.5f\n",t[i]); } } public static void main(String [] args) { Position2D pos = new Position2D(); Ecran.afficherln(EPSILON); Ecran.afficherln(pos.x," ",pos.y); affichageTableau(initRandCroissant(10)); } } L'ajout du mot réservé public aux déclarations: - de la constante EPSILON, - du type agrégé Position2D, - des champs x et y du type agrégé Position2D, - des fonctions initRandCroissant et affichageTableau conduit au résultat suivant. Un onglet supplémentaire apparait à gauche pour le type agrégé Exemple.Position2D. Une zone "Nested Class Summary" (classes imbriquées) apparait à droite pour lister les types agrégés définis (Position2D) dans (par imbrication) la classe Exemple ainsi qu'une zone "Field Summary" pour les champs (constante EPSILON) de la classe Exemple. Si on clique sur l'onglet "Exemple.Position2D" à gauche, on accède à une page web spécifique à la description de ce type agrégé avec trois zones "Field Summary" (champs x et y), "Constructor Summary" (non décrit ici) et "Method Summary" (vide). Tous les items que l'on souhaite commenter apparaissent maintenant, mais sans commentaire. Insérer des commentaires Javadoc Le langage Java admet deux techniques pour insérer des commentaires génériques dans du code source: (1) Insérer un // a pour conséquence d'exclure de la compilation tout ce qui est placé après le // jusqu'au bout de la ligne. (2) Utiliser un couple /* */ a pour conséquence d'exclure de la compilation tout ce qui se trouve entre le /* et le */ même si le */ ne se trouve pas à la même ligne de code que le /*, c'est à dire à une ou plusieurs lignes en dessous. Le formatage des commentaires Javadoc reprend la méthode (2) ci-dessus: Toutes les zones de commentaire génériques qui débutent par /**, / immédiatement suivi de deux * consécutifs, et qui se finissent par */ seront considérées comme des commentaires classiques et donc non compilées mais aussi interprétées comme des commentaires Javadoc si cet utilitaire est employé. Chacune de ces zones, suivant l'endroit où elle est placée, correspondra au commentaire à ajouter dans les pages web de documentation: - Une zone située en entête de fichier sera reportée dans la documentation générale du fichier. - Une zone située juste avant une définition de constante se sera reportée en documentation de cette constante. - Une zone située juste avant une définition de type agrégé se sera reportée en documentation de ce type agrégé. - Une zone située juste avant une définition de champ de type agrégé sera reportée en documentation de ce champ. - Une zone située juste avant une fonction sera reportée en documentation de cette fonction. /** Commentaire de fichier. */ public class Exemple { /** Commentaire de constante. */ public final static double EPSILON = 0.00001; /** Commentaire de type agrégé. */ public static class Position2D { /** Commentaire de champ. */ public double x = 0.0; /** Commentaire de champ. */ public double y = 0.0; }; /** Commentaire de fonction. */ public static double [] initRandCroissant(int n) { int i; double [] tab = new double[n]; tab[0] = Math.random(); for ( i = 1 ; i < tab.length ; i = i+1 ) { tab[i] = tab[i-1]+Math.random(); } return tab; } /** Commentaire de fonction. */ public static void affichageTableau(double [] t) { int i; for ( i = 0 ; i < t.length ; i = i+1 ) { Ecran.formater("%8.5f\n",t[i]); } } /** Commentaire de fonction. */ public static void main(String [] args) { Position2D pos = new Position2D(); Ecran.afficherln(EPSILON); Ecran.afficherln(pos.x," ",pos.y); affichageTableau(initRandCroissant(10)); } } Le code source précédent conduit aux fichiers Javadoc suivants où la structure de la documentation n'a pas changé, mais où les zones en commentaire ont été placées dans les fichiers par Javadoc. Convention de formatage des commentaires Javadoc Oracle, éditeur du langage Java, utilise une convention de formatage précise pour la documentation de ses fichiers sources Java. Celle-ci est communément utilisée par la communauté des développeurs. (1) Le /** est seul sur sa ligne. Le / est aligné horizontalement sur l'item concerné par la zone de commentaire qui débute. (2) Le */ est seul sur sa ligne. Le * est aligné horizontalement sur le premier * du /** correspondant. (3) Les commentaires sont placés sur des lignes ajoutées entre la ligne du /** et la ligne du */. Chacune de ces lignes débute par un * aligné horizontalement sur le premier * du /** correspondant, suivi d'un espace, suivi de la ligne de commentaire. Le caractère * surnuméraire sera éliminé par Javadoc. Les lignes ainsi créées seront automatiquement concaténées avec maintien d'un espace par Javadoc pour former un paragraphe unique dans la page web générée. Le code source suivant correctement commenté conduit au résultat accessible par ce lien. /** * Programme de démonstration de génération * de commentaires javadoc. */ public class Exemple { /** * Constante de définition de la précision. */ public final static double EPSILON = 0.00001; /** * Type agrégé de modélisation d'une position * en deux dimensions réelles. * Initialisation des champs à 0.0. */ public static class Position2D { /** * Abscisse */ public double x = 0.0; /** * Ordonnée */ public double y = 0.0; }; /** * Génération d'un tableau de réels tirés au sort * et ordonnés par ordre croissant. * Le tableau est généré en tirant au sort entre 0.0 et 1.0 * le premier réel (indice 0) puis en générant chacun des réels * suivants (d'indice i) en ajoutant au réel précédent (d'indice i-1) * un réel tiré au sort entre 0.0 et 1.0. */ public static double [] initRandCroissant(int n) { int i; double [] tab = new double[n]; tab[0] = Math.random(); for ( i = 1 ; i < tab.length ; i = i+1 ) { tab[i] = tab[i-1]+Math.random(); } return tab; } /** * Affichage d'un tableau de réels. */ public static void affichageTableau(double [] t) { int i; for ( i = 0 ; i < t.length ; i = i+1 ) { Ecran.formater("%8.5f\n",t[i]); } } /** * Programme principal. */ public static void main(String [] args) { Position2D pos = new Position2D(); Ecran.afficherln(EPSILON); Ecran.afficherln(pos.x," ",pos.y); affichageTableau(initRandCroissant(10)); } } Enrichissements Javadoc permet un nombre très important d'enrichissements apportables aux pages web de documentation générées. Il n'est pas question d'en dresser ici une liste exhaustive mais seulement d'en indiquer un certain nombre d'utiles. Introduire un saut de ligne Javadoc supprime les sauts à la ligne placés dans les commentaires tapés dans le code. Un moyen pour insérer un saut de ligne consiste à placer un <br> (tag de saut à la ligne du langage html) là où il est souhaité. Cette marque sera détectée par Javadoc, et conduira dans la documentation à l'obtention d'un saut à la ligne. Rôle du caractère point A l'exception des commentaires associés au fichier, tous les autres types de commentaires (constante, type agrégé, champ de type agrégé, fonction) ont pour conséquence une double apparition dans les pages web: une première apparition dans un tableau listant tous les items du même type qui sont documentés, puis, plus bas dans la page web, une seconde apparition dans une seconde liste de tous les items du même type. Ce système de double apparition a pour but d'obtenir en haut de la page web des tables qui donnent des listes d'items munis individuellement d'une courte description et, en bas de la page web, des listes de ces mêmes items, mais individuellement munis d'une description aussi précise que nécessaire. L'ensemble de ce qui est écrit dans une zone commentaire est reporté dans la description précise. Tout ce qui est écrit jusqu'au premier point inclus (la première phrase) est reporté dans la description succincte. @param et @return pour les fonctions Javadoc propose un enrichissement extrêmement intéressant dédié uniquement aux fonctions. Il est en effet possible de documenter les paramètres d'entête ainsi que la valeur retournée s'il y en a une. Chaque paramètre d'entête est documenté en indiquant d'abord @param puis, après un espace, en donnant le nom du paramètre et en finissant, après un nouvel espace, par la description du paramètre. La valeur retournée est documentée en indiquant @return suivi d'un espace puis en finissant par la description. Si une description associée à un @param ou un @return s'étend sur plusieurs lignes, celles-ci sont concaténées avec maintien d'un espace entre les éléments concaténés. Les lignes sélectionnées courent jusqu'au prochain @param, jusqu'au prochain @return ou jusqu'à la fin de la zone de commentaire si aucun @param ou @return n'est trouvé. Contrairement au paragraphe précédent, le premier point trouvé n'a aucun rôle. @author et @version La zone de commentaire d'un fichier peut être documentée avec des entrées @author pour indiquer le ou les auteurs du fichier et/ou @version pour indiquer le ou les versions du contenu du fichier. Les entrées @author se traduiront par l'ajout d'une zone Author: dans le fichier de description avec l'indication de la liste des auteurs établie par concaténation de toutes les entrées @author. Les entrées @version se traduiront par l'ajout d'une zone Version: dans le fichier de description avec l'indication de la liste des versions établie par concaténation de toutes les entrées @version. Le code source suivant présente des exemples des enrichissements présentés ci-dessus. La documentation obtenue est accessible par ce lien. /** * Programme de démonstration de génération * de commentaires javadoc. * @author Nicolas JANEY * @author nicolas.janey@univ-fcomte.fr * @version 1.0, 01/08/17 * @version 1.2, 31/08/17 */ public class Exemple { /** * Constante de définition de la précision. */ public final static double EPSILON = 0.00001; /** * Type agrégé de modélisation d'une position * en deux dimensions réelles.<br> * Initialisation des champs à 0.0. */ public static class Position2D { /** * Abscisse */ public double x = 0.0; /** * Ordonnée */ public double y = 0.0; }; /** * Génération d'un tableau de réels tirés au sort * et ordonnés par ordre croissant.<br> * Le tableau est généré en tirant au sort entre 0.0 et 1.0 * le premier réel (indice 0) puis en générant chacun des réels * suivants (d'indice i) en ajoutant au réel précédent (d'indice i-1) * un réel tiré au sort entre 0.0 et 1.0. * * @param n La taille du tableau à générer. * @return Le tableau de réels généré. */ public static double [] initRandCroissant(int n) { int i; double [] tab = new double[n]; tab[0] = Math.random(); for ( i = 1 ; i < tab.length ; i = i+1 ) { tab[i] = tab[i-1]+Math.random(); } return tab; } /** * Affichage d'un tableau de réels. * * @param t Le tableau de réels à afficher. */ public static void affichageTableau(double [] t) { int i; for ( i = 0 ; i < t.length ; i = i+1 ) { Ecran.formater("%8.5f\n",t[i]); } } /** * Programme principal. * * @param args Le tableau des paramètres d'exécution. */ public static void main(String [] args) { Position2D pos = new Position2D(); Ecran.afficherln(EPSILON); Ecran.afficherln(pos.x," ",pos.y); affichageTableau(initRandCroissant(10)); } }