Java : Javadoc

Achref El Mouelhi

Docteur de l’université d’Aix-Marseille

Chercheur en Programmation par contrainte (IA)
Ingénieur en Génie logiciel

elmouelhi.achref@gmail.com

H & H: Research and Training 1 / 18

 Plan

1 Introduction

2 Syntaxe

3 Javadoc et Eclipse

4 Doxygen : installation et génération de documentation

H & H: Research and Training 2 / 18

 Introduction

Javadoc

Définition
Il s’agit d’un document PDF, HTML ou autre qui permet de décrire le
I c

fonctionnement d’une application Java.
ELH
U
L MO
f E
chre
c A

H & H: Research and Training 3 / 18

 Introduction

Javadoc

Définition
Il s’agit d’un document PDF, HTML ou autre qui permet de décrire le
I c

fonctionnement d’une application Java.
ELH
U
L MO
f E
ràerédiger.
c h
Ce n’est pas un rapport
c A

H & H: Research and Training 3 / 18

 Introduction

Javadoc

Définition
Il s’agit d’un document PDF, HTML ou autre qui permet de décrire le
I c

fonctionnement d’une application Java.
ELH
U
L MO
f E
ràerédiger.
c h
Ce n’est pas un rapport
c A
C’est plutôt un rapport à générer à partir de notre code-source.

H & H: Research and Training 3 / 18

 Introduction

Javadoc

Pourquoi ? !
I c
Avoir une idée sur la structure de l’application
E L H
U
MO
Permettre de bien comprendre le fonctionnement
L
Faciliter la maintenancef E
c h re
Éviter de lireA
c leplusieurs
comprendre
(milliers voire plus) de lignes de code pour
fonctionnement de l’application

H & H: Research and Training 4 / 18

 Introduction

Javadoc

I c
Principe
H
Bien commenter le code (respecterO UELrègles)
certaines
L M l’extraction des
f
Générer la documentation E en faisant
commentaires eth enre
c établissant les différents liens entre éléments
c A

H & H: Research and Training 5 / 18

 Syntaxe

Javadoc

3 types de commentaires

Commentaire mono-ligne
// commentaire sur une seule ligne I c

ELH
U
Commentaire multi-ligne
L MO
/* commentaire sur
f E
c
plusieurs lignes */
A hre
c
pour annotation et documentation
Commentaire
/** commentaire pour
documentation */

H & H: Research and Training 6 / 18

 Syntaxe

Javadoc

Règles
Un commentaire de documentation concerne un élément de notre
code source
une classe
I c

un attribut de classe
ELH
U
une variable
L MO
f E
hre
une méthode
...
A c
c
Pas de ligne vide entre un commentaire de documentation et
l’élément commenté
Un commentaire de documentation peut avoir un (ou même
plusieurs) attributs (appelés aussi balises)

H & H: Research and Training 7 / 18

 Syntaxe

Javadoc
Attributs
@author : permet d’indiquer l’auteur (ou les auteurs) participant
au code source

I c

/**
* @author Wick ELH
U
*/
L MO
public class Personne{ }
f E
chre
c A

@see : effectue un renvoi vers une autre classe ou fonction...
/**
* @see Adresse
*/
private Adresse adresses[] = new Adresse[5];

H & H: Research and Training 8 / 18

 Syntaxe

Javadoc

Attributs
@version : permet de définir la version d’un fichier
I c

/**
ELH
* @version 3.2beta
U
*/
L MO
f E
re d’indiquer que le code marqué est
@deprecatedc: h
permet
c A
obsolète
@class : permet de décrire une classe
@exception : permet de décrire une classe exception

H & H: Research and Training 9 / 18

 Syntaxe

Javadoc

Attributs
@return : permet de décrire la valeur de retour d’une méthode.
I c
@throws : indique qu’une méthode peut lever une exception
H
ELètres d’une
@param : permet de lister et décrire lesUparam
méthode
L MO
/**
h r e fE
* @paramAc
c var1
* @param ...
description1

* @param varN descriptionN

*/

H & H: Research and Training 10 / 18

 Javadoc et Eclipse

Javadoc

Sous Eclipse
I c
l’E
L H
Pour commenter un élément : cliquer sur U élement et faire
alt+shift+j
L MO
r e
Pour générer la Javadoc
h f :Ealler dans le menu Project et choisir
A c Javadoc
l’option Generate
c

H & H: Research and Training 11 / 18

 Doxygen : installation et génération de documentation

Javadoc

Doxygen pour générer la documentation JAVA

c
Supporte plusieurs langages de programmations C, C++, Java,
I
C#...
EL H
U
Opossible HTML, PDF, XML,
M
Plusieurs formats de documentation
L
LATEX...
h r e fE
A cWindows, Mac et Linux
Disponible sous
c
Même syntaxe ou presque pour les autres langages et pour les
autres générateurs

H & H: Research and Training 12 / 18

 Doxygen : installation et génération de documentation

Javadoc

Téléchargement

Télécharger Doxygen :
http://www.stack.nl/∼dimitri/doxygen
I c

/download.html#latestsrc
H
EL certaines
Télécharger Graphviz qui permettra de
O U visualiser
propriétés (telles que l’héritage)M
fE L via des graphes :
r
http://www.graphviz.org/
c h e
TéléchargerA
c
HTML WorkShop :
https://www.microsoft.com/en-us/download/
details.aspx?displaylang=en&id=21138
Télécharger Miktex si vous voulez générer de la documentation
PDF ou PS : https://miktex.org/2.8/setup

H & H: Research and Training 13 / 18

 Doxygen : installation et génération de documentation

Javadoc

I c

Installation et lancement
E LH
U
MO
Installer tous les fichiers téléchargés
L
Lancer doxywizard.exe
h r e fE
A c
c

H & H: Research and Training 14 / 18

 Doxygen : installation et génération de documentation

Javadoc

Utilisation : l’onglet Wizard

c
Dans le menu Project, il faut préciser les données relatives au
I
EL H
projet (répertoire code source, répertoire destination...)
U
MO JAVA
Dans le menu Mode, on choisit l’option
L
r e
Dans le menu Output,
h fonEchoisit le format de documentations à
générer A c
c
Dans le menu Diagrams, on choisit les types de diagrammes à
générer...

H & H: Research and Training 15 / 18

 Doxygen : installation et génération de documentation

Javadoc

Utilisation : l’onglet Expert

I c
Dans le menu Project, on peut forcer l’utilisation d’un codage,
modifier la langue du document à générer
EL H
O
Dans le menu Build, on peut afficher U
la documentation pour les
M
Layant le qualificateur private,
static... re f E
fonctions/méthodes/membres

c h
AInput, ça nous permet de définir le codage utilisé
Dans lecmenu

pour nos fichiers sources
...

H & H: Research and Training 16 / 18

 Doxygen : installation et génération de documentation

Javadoc

I c
Utilisation : l’onglet Run EL H
U
L
Le bouton Run doxygen permet MdeOgénérer la documentation
h r e fE
A c
c

H & H: Research and Training 17 / 18

 Doxygen : installation et génération de documentation

Javadoc

I c
ELH
Plus de détails
U
L MO
http://www.stack.nl/∼dimitri/doxygen/index.html

h r e fE
A c
c

H & H: Research and Training 18 / 18