Documenter son projet

Toutes les entités publiques de votre projet — classes, interfaces, attributs et méthodes publiques — doivent être documentées au moyen de commentaires Javadoc. Vous pouvez écrire ces commentaires en français ou en anglais, en fonction de votre préférence, mais vous ne devez utiliser qu'une seule langue pour tout le projet.

Les commentaires Javadoc sont des commentaires structurés que l'on peut attacher aux différentes entités d'un programme. On les reconnaît au fait qu'ils commencent par une barre oblique suivie de deux astérisques (/**).

Les commentaires Javadoc peuvent inclure des étiquettes (tag), qui commencent par un arobas (@). Même s'il existe de nombreuses étiquettes, les plus importantes sont :

1. L'étiquette @author, qui est suivie du nom d'un des auteurs de la classe ou interface à laquelle elle est attachée. Peut apparaître plusieurs fois s'il y a plus d'un auteur.
2. L'étiquette @param, qui est suivie du nom d'un paramètre de l'entité à laquelle on l'attache (méthode ou constructeur) et d'une description de la signification de ce paramètre.
3. L'étiquette @throws, qui est suivie du nom d'une exception qui peut être levée par la méthode à laquelle on l'attache et d'une description des cas dans lesquels elle est levée.
4. L'étiquette @return, qui est suivie d'une description de la valeur retournée par la méthode à laquelle on l'attache.

Pour votre projet, vous avez l'obligation de lister la totalité des auteurs de chaque classe, interface ou énumération publique que vous rendez. Le prénom et le nom de chaque auteur doit être suivi de son numéro SCIPER entre parenthèses.

Pour illustrer l'utilisation des différentes étiquettes mentionnées plus haut, voici ce à quoi la documentation d'une classe modélisant un nombre rationnel pourrait ressembler :

/**
 * Un nombre rationnel.
 *
 * @author Marie Durand (654321)
 * @author Jean Dupond (123456)
 */
public final class Rational {
  private final int numerator, denominator;

  /**
   * Construit un nombre rationnel avec le numérateur
   * et le dénominateur donnés.
   *
   * @param numerator
   *            le numérateur
   * @param denominator
   *            le dénominateur (doit être non nul)
   * @throws IllegalArgumentException
   *             si le dénominateur est nul
   */
  public Rational(int numerator, int denominator) {
    if (! (denominator != 0))
      throw new IllegalArgumentException();
    this.numerator = numerator;
    this.denominator = denominator;
  }

  /**
   * Retourne le numérateur de ce nombre rationnel.
   * @return le numérateur de ce nombre rationnel
   */
  public int numerator() {
    return numerator;
  }

  // … méthodes
}

IntelliJ insère automatiquement un certain nombre d'étiquettes (p.ex. @param et @return pour les méthodes) lorsqu'on insère un début de commentaire Javadoc (/**) puis qu'on presse la touche d'entrée (⏎).

Eclipse offre quant à lui deux commandes qui sont d'une grande aide lorsqu'on rédige des commentaires Javadoc :

1. Dans le menu Source, l'entrée Generate Element Comment permet de générer un squelette de commentaire Javadoc pour l'élément sous le curseur.
2. Dans le menu Source, l'entrée Format Element permet de reformatter l'élément sous le curseur. Lorsqu'on l'utilise dans un commentaire Javadoc, celui est reformatté de manière plaisante.