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 trois barres obliques¹ (///).

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 :

@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.

@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.

@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.

@return

qui est suivie d'une description de la valeur retournée par la méthode à laquelle on l'attache.

Les étiquettes reconnues, ainsi que la syntaxe détaillée des commentaires JavaDoc, sont décrites dans le document JavaDoc Documentation Comment Specification for the Standard Doclet.

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 (ne doit pas être 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
}