documentation Archives

Mai

Java – Générateur de documentation Java

Categories: java

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 :

All posts tagged documentation

PHP MySQL – Site officiel et documentation

Java – Générateur de documentation Java