Outils de tests, logs et documentation

Frédéric Moal année 2010/2011

POO

2

De nombreux outils à l’aide du développeur

Les IDELes générateurs de documentation : exemple de javadocGestion des traces d’exécution : logs et assertionsL’automatisation de tests unitaires : JUnitLes systèmes de gestion de version

3

Gestion de la documentation :javadoc

4

Généralités

javadoc produit de la documentation en partant de commentaires particuliers insérés dans le code source des classes (/** . . . */)On peut ainsi documenter

paquetagesclasses ou interfacesvariables d'instanceméthodes

5

Format des commentairesLes commentaires peuvent contenirdu texte simpledes tags HTML de mise en forme de texte (italique, caractère gras, caractères à espacement fixe,…) ; un tag bien utile est <code> (et </code>) pour inclure du code dans les commentairesdes tags spéciaux à javadoc, qui commencent par le caractère @ : @author, @version, @param,…Les commentaires doivent être placés juste avant ce qu'ils commentent

6

Caractères spéciauxLes caractères liés à HTML comme « < »  ou « > » sont interprétés spécialement par javadoc« < » doit être écrit « &lt; » dans la javadocDepuis le JDK 5.0 les tags @literal permet d’insérer plus facilement les caractères spéciaux ; par exemple {@literal A<B>C} sera affiché A<B>C par la javadoc{@code A<B>C} fait la même chose en ajoutant la police de caractères du tag HTML <code>

7

Insérer une référence

Les tags @see et @link permettent d’insérer une référence vers une autre partie de la documentation ou même vers une autre documentation quelconquePlusieurs formats peuvent être utilisés pour indiquer ces références ; ils sont donnés dans les transparents suivants

8

Formats de référence (1)

chaîne de caractères quelconque : la chaîne sera affichée telle quelle dans la javadocExemple :@see "The Java Programming Language"<a href="URL#ancre">label</a> : lien vers une adresse Web (adresse absolue ou relative)Exemple :@see <a href="spec.html#section">Java Spec</a>

9

Formats de référence (2)

@see  package.Classe#membre  labellien vers un autre endroit de la javadoc (ou vers une autre javadoc si l’option -link est utilisée au lancement de la commande javadoc

Le texte du lien sera « label »Remarquez le # à la place d'un « . » entre le nom de la classe et le nom de la méthode

10

Formats pour package.Classe#membre

Le membre peut être un constructeur, une méthode ou une variable d’instanceOn peut aussi désigner une classe par package.Classe, ou une classe interne par package.Classe.ClasseInterne (ne jamais omettre la classe englobante, même si le commentaire est dans la classe englobante)On peut aussi désigner un paquetage : @see fr.miage.tools

11

Formats pour package.Classe#membre

Si la classe appartient au paquetage de la classe documentée ou si la classe est importée, on peut omettre le nom du paquetage :@see ClasseSi le membre appartient à la classe qui est documentée, on peut omettre package.Classe : Utilisez la méthode {@link #getComponentAt(int, int) getComponentAt}.Si la méthode n’est pas surchargée, le nom de la méthode suffit ; sinon il faut indiquer sa signature

12

Section « see also »

@see crée une entrée dans la section « see also » de la documentation Exemples :@see java.lang.Integer#parseInt label@see <a href="…">label</a>(si le 1er caractère est "<", c'est un lien HTML)@see "texte quelconque"

13

Exemple de @see

@see "The Java Programming Language"@see <a href="spec.html#section">Java Spec</a>Pour désigner des méthodes de la classe ou d’une autre classe :@see equals@see String#equals(Object) equalsLe label qui

sera affichéLes classes sont cherchées dans le classpath

Pour les méthodes surchargées

14

Liens entre commentaires

{@link nom-classe#membre label}permet de placer un lien n'importe où dans la documentation (ne pas oublier les accolades)Exemple :Utilise la méthode {@link #getComponentAt(int, int) getComponentAt}.@linkplain a une syntaxe identique à @link mais le label est affiché dans la police de caractères du texte ordinaire et pas dans la police du code

15

Commentaires @since

@since permet d'indiquer une version depuis laquelle ce qui est commenté a été introduitExemple :@since JDK1.1

16

Commentaires de classe et d'interface

@param <E> description de ce que représente le paramètre de type <E> (depuis le JDK 5.0)@author nomindique l'auteur (plusieurs fois si plusieurs auteurs)@author texteindique le ou les auteurs en utilisant le texte@version texteprécise la versionCes 2 tags ne sont utilisés dans la documentation que si on donne les options -author et -version de la commande javadoc

17

Commentaires de méthodes

Tous les tags de même type doivent se suivreLes descriptions peuvent s'étaler sur plusieurs lignes@param paramètre descriptiondocumente un paramètre de la méthode@param <T> descriptiondocumente un paramètre de type <T> de la méthode (ne pas omettre les < et >)@return descriptiondocumente ce que retourne la méthode@throws classe_exception descriptiondocumente une exception (on peut aussi utiliser @exception)

18

Résumé de commentaire

La première phrase du commentaire d’un membre d’une classe constitue le résumé du commentaireCe résumé est affiché dans la section « résumé »Le reste peut être vu en suivant le lien de la section résuméLa « première phrase » se terminepar un point suivant d’un espace ou d’une fin de ligneou par un tag javadoc comme @param ou @return

19

Exemple de documentation de méthode

/** * Returns the character at the specified index. An

index * ranges from <code>0</code> to <code>length() -

1</code>. * * @param index the index of the desired character. * @return the desired character. * @throws StringIndexOutOfRangeException * if the index is not in the range

<code>0</code> * to <code>length()-1</code>. * @see java.lang.Character#charValue() */ public char charAt(int index) {

20

Héritage des commentaires

Si la méthode d’une classe n’a pas de commentaire, elle hérite automatiquement des commentaires de la méthode qu’elle redéfinit ou implémente (s’ils existent)Avant la version 5 de java, si la méthode ajoutait un commentaire, il fallait ajouter « {@inheritDoc} » pour demander cet héritage des commentairesDepuis la version 5, les commentaires pour un paramètre, la valeur retour ou une exception sont hérités automatiquement ; d’autres commentaires peuvent être ajoutés dans la méthode

21

Commentaires de paquetage

Ils doivent être placés dans un fichier nommé package-info.java placé dans le répertoire des fichiers source du paquetage, avec les fichiers .javaAvant le JDK 5.0, le fichier devait s’appeler package.html ; le JDK 5.0 accepte un des 2 fichiers (mais pas les 2)Les contenus de package-info.java et de package.html diffèrent

22

package.html

C’est un fichier html ordinaireTout ce qui est entre <BODY> et </BODY> se retrouve dans la documentationLa 1ère phrase (jusqu'à un ".") doit être un résumé de ce que contient le paquetageExemples de tags utilisables dans le corps du fichier html : @see, @since, @link

23

Exemple de package.html

<html>

<body>

Ce paquetage ….

. . .

@since 1.1

</body>

</html>

24

package-info.java

Il ressemble à un commentaire javadoc habituelLa 1ère phrase (jusqu'à un ".") doit être un résumé de ce que contient le paquetageExemples de tags utilisables dans le corps du fichier html : @see, @since, @link

25

Exemple de package-info.java

/** * Ce paquetage ... . * <p> * ... * (voir la classe {@link truc.Classe1})

* ... * @since 1.1 * @see java.awt */package truc.machin;

26

Commentaires généraux

De même, un fichier de nom quelconque (typiquement un fichier placé à la racine des fichiers source et nommé overview.html) peut être placé dans le répertoire parent de tous les fichiers source ; ce fichier contient des commentaires sur tout le codeLe contenu de ce fichier sera affiché quand l'utilisateur cliquera sur le lien « Overview » de la documentation si on génère la documentation avec l’option « –overview nom-fichier.html »

27

Fichiers annexesSi la documentation d’un paquetage utilise des fichiers annexes, par exemple des images, on doit les placer dans un répertoire nommé doc-files du paquetageCes fichiers pourront être référencés par un nom relatif commençant par doc-files :/** * Image du bouton : * <img src="doc-files/Bouton.gif"> */

28

Syntaxe de la commandejavadoc [options…] [cheminsSourcesClasses…] [nomsPaquetages]Si on donne des noms de paquetages en paramètres, les fichiers sources doivent être dans un répertoire qui correspond au nom du paquetageL’option –sourcepath indique sous quel répertoire trouver les sources des classes des paquetages quand on donne nomsPaquetages ; elle n’est pas utilisée si on donne cheminsSourcesClasses

29

Options de la commande (1)

Options (quelques options seulement) :-d répertoire : indique le répertoire dans lequel mettre la documentation (répertoire courant par défaut)-protected, -public, -package, -private : indique les membres et constructeurs qui apparaîtront dans la documentation (protected par défaut)-author, -version : l’auteur et la version seront affichés (par défaut, ils ne le sont pas)

30

Options de la commande (2)

-link URLautreJavadoc : permet de faire des liens vers une autre documentation javadoc préexistante (on peut donner plusieurs options –link) ; on peut donner un chemin relatif (tenir alors compte des chemins de destination de la javadoc) ou absolu-sourcepath : indique où trouver les fichiers sources des paquetages dont on veut créer la documentation (par défaut, ils sont cherchés dans le classpath)-classpath : comme pour les autres outils

31

Options de la commande (3)

-use : génère un lien qui indique par qui est utilisé une classe ou un paquetage-overview nom-fichier.html : indique un fichier qui donne une vision d’ensemble du code du projetplusieurs options pour donner des titres, en-têtes ou pieds de pages à la documentation (voir documentation de Sun)

32

Exemples

javadoc

-link http://www.miage.fr/Java/jdk1.2/apifr.miage.orleans.maLibrairie

33

Option -linkoffline

Il est possible que la javadoc d’un paquetage ne soit pas accessible pendant l’exécution de javadoc car javadoc a seulement besoin du fichier package-list placé avec la javadoc de l’autre paquetageEn ce cas, on peut remplacer l’option –link par une option « –linkoffline urlExterne repListeLocale »urlExterne est l’url qu’on aurait donné à l’option –linkrepListeLocale est le répertoire où on a rangé le fichier package-list manquant, que l’on a réussi à récupérer par un moyen ou par un autre

34

Fichier package-list

Le fichier package-list est généré automatiquement par javadoc ; il est placé dans le répertoire qui contient la javadoc générée par une commande javadoc uniqueIl contient les noms des paquetages dont le répertoire contient la javadocIl est utilisé par javadoc pour faire les liens HTML qui référencent des éléments d’un autre paquetage : quand il y a une option –link, il utilise ce fichier pour savoir rapidement comment faire ces liens (il ne rentre pas dans les détails des fichiers associés à la javadoc extérieure)

35

Problème avec les liens

Si on génère séparément la javadoc de 2 paquetages p1 et p2 inter-dépendants, le fichier package-list n’existera pas lors de la première exécution de javadoc et la javadoc de p1 n’aura pas de liens vers p2En ce cas, il faut lancer javadoc sur p1, puis sur p2, et encore une fois sur p1