All posts tagged documentation

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 :

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 :