Médiaforma

Java – Générateur de documentation Java

Print Friendly

Javadoc est un outil développé et maintenu par Oracle. Il permet de créer une documentation des API au format HTML depuis les commentaires présents dans le code source. Javadoc est le standard industriel pour la documentation des classes Java. La plupart des IDEs (c’est le cas de NetBeans par exemple) insèrent automatiquement des instructions destinées à créer la documentation HTML Javadoc de vos applications.

Voici par exemple le code généré par NetBeans lors de la création du projet monprojet :

/*
 * To change this license header, choose License Headers in Project Properties.
 * To change this template file, choose Tools | Templates
 * and open the template in the editor.
 */
package monprojet;
/**
 *
 * @author Michel
 */
public class MonProjet {
    /**
     * @param args the command line arguments
     */
    public static void main(String[] args) {
        // TODO code application logic here
    }
}

Les instructions à destination de Javadoc sont des commentaires entourés par /** et */ :

/** Ces commentaires

sont destinés au

système JAVADOC

qui génère de la documentation

API à partir du code */

Dans ces commentaires, il est possible d’insérer des tags qui ont une signification particulière. Voici quelques-uns des tags utilisables :

Tag Description
@author Nom du développeur
@deprecated Marque la méthode comme dépréciée. Certains IDEs créent un avertissement à la compilation si la méthode est appelée.
@exception Documente une exception lancée par une méthode — voir aussi @throws.
@param Définit un paramètre de méthode. Requis pour chaque paramètre.
@return Documente la valeur de retour. Ce tag ne devrait pas être employé pour des constructeurs ou des méthodes définis avec un type de retour void.
@see Documente une association à une autre méthode ou classe.
@since Précise à quelle version de la SDK/JDK une méthode a été ajoutée à la classe.
@throws Documente une exception lancée par une méthode. Un synonyme pour @exception disponible depuis Javadoc 1.2.
@version Donne la version d’une classe ou d’une méthode.

Vous pouvez vous contenter des tags ajoutés automatiquement dans votre code par NetBeans ou en ajouter manuellement pour qu’ils soient inclus dans la documentation générée. Documenter le code source directement dans le code source plutôt que dans un document séparé vous aide à garder votre documentation à jour, car vous pouvez générer votre documentation à chaque fois que le code est modifié.

Pour générer la documentation d’un projet, cliquez du bouton droit sur ce projet dans le volet Projects (appuyez sur Ctrl + 1 si ce volet n’est pas affiché), puis cliquez sur Generate Javadoc. Voici le résultat :

 

 

Pour avoir un aperçu des fichiers générés, allez dans l’onglet Files (appuyez sur Ctrl + 2 si ce volet n’est pas affiché) et développez les entrées dist puis javadoc :

 

 

Vous avez aimé cet article ? Partagez-le avec vos réseaux...
 
Comments

No comments yet.

Leave a Reply