Documentation Java

Introduction

Le code Java doit être documenté afin d'aider les autres développeurs à reprendre votre code et l'utiliser correctement. Cette documentation nommée JavaDoc possède des règles de syntaxes particulières et n'est pas à confondre avec les commentaires.

En Java, la JavaDoc revêt un caractère officiel, il est même possible de générer un site HTML statique avec toute la documentation de votre code. Alors que le commentaire est beaucoup plus libre et informel, il offre des détails ponctuels dans le code.

Règles d'écritures

Syntaxe

Il y a plusieurs règles à respecter lors de l'écriture de la JavaDoc. Si elles ne sont pas respectées des erreurs se produiront à la génération de la documentation.

**Règles de déclaration :

/** 
 *
 */

Ne peut se placer uniquement sur :
- Les classes
- Les méthodes
- Les attributs
La documentation doit commencer par une majuscule et se finir par un point.
Les généricités doivent apparaître dans la documentation.
Le retour d'une méthode apparaître dans la documentation.
Les paramètres de méthode doivent apparaître dans la documentation.

Annotation

Afin d'enrichir la documentation, il est possible de placer des annotations.

A connaître :

@param: Suivit d'un nom du paramètre ou du générique pour le documenter.
@return: Documenter le résultat d'une méthode.
@throws: Documenter le ou les exceptions levées par une méthode qu'elles soit déclarées dans la signature ou non.
@exception Documenter le ou les exceptions que l'appel de la méthode peut engendrer implicitement.
@author Indique l'auteur de la classe ou méthode.
@since Indique la version de l'application quand la classe ou la méthode a été créée.
@deprecated Documenter pourquoi cet élément est déprécié.
@see Suivit du nom complet de classe pour indiquer une référence documentaire.

Certaines annotations peuvent s'écrire entre accolades pour considérer un bloc:


/** {@code Objects.equals(a, b)} */
           ^^^^^^^^^^^^^^^^^^^^---// Petit bloc de code Java en une ligne

/** {@link Comparable} */
           ^^^^^^^^^^-------------// Lien vers une autre classe

Exemple :

/**
 * Classe mère pour toutes les opérations de persistances génériques.
 * Se base sur la technologie Jakarta EE JPA.
 *
 * @param <E> Une entité persistante sérialisable
 * @author Zelmo Academy
 * @see Serializable
 * @since 1.0
 */
public abstract class AbstractDAO<E extends Serializable>{


    /**
     * Sauvegarder une entité dans le contexte de persistance.
     *
     * @param entity Une entité persistante à créer ou mettre à jour
     * @return La valeur {@code true} si et seulement si l'état de la base de données a changé, 
     * sinon la valeur {@code false} est retournée
     * @throws DAOException si l'entité ne respecte pas les contraintes d'intégrité de la base de données
     */
    public boolean save(E entity) throws DAOException {
       // ...
    }

    /**
     * Mettre à jour une entité dans le contexte de persistance.
     *
     * @param entity entité persistante à mettre à jour
     * @deprecated Remplacer par la méthode {@code AbstractDAO.save(entity)}
     */
    @Deprecated 
    public void update(E entity){
       // ...
    }
}

Mise en forme

La JavaDoc supporte également les balises HTML pour des mises en formes avancées. Ces balises peuvent posséder l'attribut style pour utiliser les propriétés CSS.

Exemple :

/**
 * Représente un consommateur de l'application <b>BeeNews</b>.
 * Un consommateur peut:
 * <ul>
 *     <li>Acheter un produit.</li>
 *     <li>Consulter ses factures.</li>
 *     <li>Créditer sa carte de fidélité.</li>
 *     <li>Mettre à jour ses informations de compte.</li>
 * </ul>
 * <b style="color:red;">Toutes les actions métiers d'un consommateur seront tracées.</b>
 * 
 * @author Zelmo Academy
 */
public class Customer implements Serializable {

    // ...

    /**
     * Constructeur par  défaut.
     * Requis pour le fonctionnement nominal de la sérialisation.
     *
     * <pre>
     *   var cutomer = new Customer();
     *   customer.setGivenName("John");
     *   customer.setFamilyName("DOE");
     *   customer.setEmail("john.doe@sample.org");
     * </pre> 
     * @see #setGivenName()
     * @see #setFamilyName()
     * @see #setEmail()
     */
    public Customer() {
    }

    // Accesseurs & Mutateurs
    // ...

}

Note

Vous pouvez insérer des blocs de code sur plusieurs lignes en conservant le formatage avec la balise pre. Vous pouvez également utiliser la syntaxe # pour placer une ancre vers une méthode, un attribut ou une constante de cette même classe.