Tutoriel Java N°6 : Documentation de programme JAVA avec l’outil javadoc

JPG - 15.4 ko

Avec Objis, spécialiste Java depuis 2005, générez une documentation de vos programmes java avec l’outil javadoc.exe, présent dans le répertoire ’bin’ de votre kit de développement java (JDK). Intégrez javadoc à eclipse. Automatisez la génération de la documentation avec un fichier ant (javadoc.xml) .

Après avoir compris la génération de documentation d’un programme, vous découvrirez comment créer un livrable à votre client avec l’outil jar.

ASTUCE —> Soyez informé de la mise à jour de nos tutos ou de la création de nouveaux tutos.

Auteur

- Douglas MBIANDOU. Président Objis . Concepteur formation ’Nouveautés Java 8 et 9’

Prérequis

- Tutoriel Java N°3 : installation Eclipse et premier projet

Objectifs

- Comprendre le programme javadoc (JDK)
- Comprendre l’intégration de Javadoc dans Eclipse
- Automatiser la génération de la javadoc

Programme

- Partie 1 : Commentaires Javadoc dans code source java
- Partie 2 : Assistant eclipse de génération Javadoc
- Partie 3 : Automatisation de la génération javadoc (javadoc.xml)
- Conclusion

Durée

- 20 min

Partie 1 : commentaires javadoc

Le tutoriel JAVA n°3 ’Installation eclipse’ vous a permis de vous familiariser avec l’environnement de développement eclipse. En particulier, vous avez exécuté dans eclipse votre premier programme java.

tuto-6-img1

- Modifiez le programme ci-dessus de la façon suivante.

tuto-6-img-2

— Quelles sont les modifications apportées ?
— Expliquez le commentaire javadoc associé à la classe, ainsi que le commentaire javadoc associé à la méthode main().
— Analysez l’impact du raccourci clavier suivant : Alt+Shift+J
— Montrez que ce raccourci est précisé dans la liste des raccourcis Eclispe : Ctrl+Shift+L

Partie 2 : Génération Javadoc

Dans cette partie vous allez utiliser un assistant de création de la document javadoc de l’application.

- Sélectionnez le projet en cours et faire menu "Project/Generate javadoc"

tuto-6-img-3

Dans l’écran qui suit la sélection "Project/Generate javadoc" : .

- Dans la section ’Javadoc Command’ , fournissez le chemin vers l’exécutable utilisé pour la génération de la javadoc, c’est à dire de l’éxécutable javadoc.exe qui se trouve dans le répertoire ’bin’ du jdk . Par exemple le chemin ’C :\Program Files\Java\jdk1.8.0_11\bin\javadoc.exe
- Sélectionnez la visibilité ’private’ afin de créer la documentation de toutes les classes de l’application. REMARQUE le répertoire par défaut ’doc’ de destination des fichiers HTML de javadoc.

tuto-6-img-4

- Cliquez sur le bouton ’Next’. L’écran suivant apparaît

tuto-6-img-5

QUESTION : à quoi servent les tags javadoc @author , @version et @deprecated ?

- Cliquez sur le bouton ’Next’. L’écran suivant apparaît

tuto-6-img-6

- Cocher l’option ’Save the settiings of this javadoc export as an Ant script’. Cela permet d’enregistrer la configuration de génération javadoc dans un script ant.

Pour regénérer la javadoc ultérieurement, il suffira d’exécuter le script (click droit sur le script javadoc.xml / Run / Ant Build)

- Cliquez sur le bouton ’Finish’.

L’écran suivant apparaît.

tuto-6-img-7

- Validez (Bouton YES) ce message,qui informe de la création du répertoire doc.

Le message suivant apparaît, informant de la création du fichier ANT javadoc.xml, clé de l’automatisation des futures javadoc

tuto-6-img-8

- Cliquez sur OK

le répertoire ’doc’ et le fichier javadoc.xml apparaissent dans le worskpace.

tuto-6-img-9

REMARQUE : vous n’avez pas besoin ici de comprendre le contenu du fichier javadoc.xml. Pour une compréhension de ANT, découvrez nos tutoriaux ANT.

- Click droit / Refresh sur le répertoire ’doc’

- voir le contenu du répertoire doc

tuto-6-img-10

La javadoc du projet apparaît.

tuto-6-img-11

- Double-click sur fichier ’index.html’

tuto-6-img-12

- Cliquer sur le lien de la classe ’HelloObjis’

PNG - 48.1 ko
tuto-6-img-13

Partie 3 : automatiser la génération

- Modifier le commentaire de la classe

tuto-6-img-14

tuto-6-img-15

- Click droit sur le script javadoc.xml / Run / Ant Build

tuto-6-img-16

Le script de génération de la javadoc se lance :

tuto-6-img-17

- La javadoc est régénérée avec nos options.

tuto-6-img-18

Notre modification de commentaire avec la version a été prise en compte.

Conclusion

Ce tutoriel vous a permis de vous familiariser avec la création de documentation de code source java avec l’outil javadoc.exe et l’environnement de développement eclipse.

Le tutoriel suivant ’Tutoriel JAVA N°7 : création d’archives JAR’ permettra de vous familiariser avec la création d’archives JAR dans l’environnement de développement eclipse.

Votre avis nous intéresse

Vous avez remarqué une erreur ? Vous avez une recommandation pour améliorer ce tuto ? Vous souhaitez nous encourager à partager notre savoir-faire technique et pédagogique ?

Donner votre avis sur ce Tuto objis.com

Professionnels : maîtrisez les nouveautés Java 8 et 9 !

JPG - 8.3 ko

A travers notre nouvelle formation Nouveautés Java 8 et 9 (durée 4 jours) conçue par l’auteur de ce tutoriel, découvrez par la pratique le nouveau système de Modules Java 9 (Encapsulation forte + Intercafes + Dépendances explicites) ainsi que les spécificités de Java 8 (Streams, Lambda, Optional...). Maîtrisez également la méthodologie de migration de votre code vers Java 9. Un sérieux atout pour votre employabilité et l’évolution de votre carrière professionnelle !. Contactez-nous dès maintenant !