Documentation de programmes

Voir aussi :

• La page de Sun consacrée à la JavaDoc

Pourquoi documenter le code ?

• si vous documentez votre code, vous comprendrez mieux ce que vous avez écrit
• votre code sera sans doute lu ou modifié par d'autres
• la doc réduit le coût de la maintenance du code
• le code et sa documentation ne peuvent pas être séparés (autrement, il serait difficile d'assumer leur concordance)

Documentation de l'interface

• des commentaires utilisés pour donner information aux usagers du programme; ceux derniers ont seulement besoin de l'information concernant l'usage de la classe - son interface.
• Javadoc est un outil développé par Sun Microsystems qui permet, en inspectant le code Java des classes, de produire une documentation d'API de votre code
• inclus dans tous les JDK (ou SDK) de Java
• la documentation générée par Javadoc est appelée souvent javadoc
• l'outil génère des pages HTML contenant au minimum les listes des classes, des méthodes et des variables publiques
• les doclets permettent d'exporter la doc JavaDoc en différents formats, tels que PDF, XML, DocBook, LaTeX, etc

Les commentaires Javadoc

• chaque commentaire java commençant par /** sera intégré dans la documentation du code source
• ces commentaires utilisent des tags Javadoc qui commencent par un @
• le tableau suivant résume les tags utilisés :

  TagDescription
  @author	nom du développeur
  @deprecated	marque la méthode comme dépréciée
  @exception	documente une exception lancée par une méthode
  @param	définit un paramètre de méthode
  @return	documente la valeur de retour; ce tag ne devrait pas être employé pour des méthodes définies avec un type de retour void
  @see	documente une association à une autre méthode ou classe
  @since	précise à partir de quelle version une méthode existe dans la classe
  @throws	documente une exception lancée par une méthode; un synonyme pour @exception
  @version	définit la version d'une classe ou d'une méthode

• exemple :

  package base;
  
  /**
   * <p>Cette classe sert à la gestion de questions à choix multiples à réponses
   * multiples. Chaque objet de cette classe contient une question textuelle,
   * une liste de choix de réponse possibles et l'information si le choix de
   * réponse donné est valid (vrai) ou non (faux). Tous les choix de réponse
   * doivent être différents.</p>
   *
   * <p>L'énoncé de chaque choix de réponse doit contenir une chaîne de caractères
   * valide, c.-à-d. il ne peut pas être une chaîne de caractères vide ou une
   * chaîne de qui contient uniquement des espaces.</p>
   *
   * <p>La position du premier choix est zéro.</p>
   */
  public class QuestionChoixMReponseM extends Question {
  
    /**
     * Ajouter un choix de réponse à une question à choix multiples à réponses
     * multiples.
     *
     * @param indice
     *          position après laquelle le choix sera ajouté; 0 correspond à
     *          l'ajout au début
     * @param choix
     *          la description textuelle du choix à ajouter
     * @throws InvalidStringException
     *           si une chaîne de caractères est invalide
     * @throws NonExistentException
     *           si la position est invalide
     * @throws AlreadyExistsException
     *           si le choix de réponse déjà existe
     */
    public void ajouterChoix(int indice, String choix)
        throws InvalidStringException, NonExistentException,
        AlreadyExistsException {
      if (choix.trim().equals(""))
        throw new InvalidStringException("Énoncé manquant");
      else if (indice < 0 || indice > listeChoix.size())
        throw new NonExistentException("Position invalide");
      else if (estDans(listeChoix, choix))
        throw new AlreadyExistsException("Choix déjà existant");
      else {
        ChoixDeReponse nouveauChoix = new ChoixDeReponse(choix);
        listeChoix.insertElementAt(nouveauChoix, indice);
      }
  
    }
    ...
  }

  

  

Documentation de l'implémentation

Cette doc est destinée aux programmeurs qui vont modifier le fichier dans l'avenir et qui ont besoin d'une connaissance des détails de l'implémentation.

• expliquer le choix technique effectué
• pourquoi tel algorithme et pas un autre
• problèmes à corriger
• ...

Exemple :

  private int nbr; // nombre de lignes dans le fichier
  ...
  // la méthode de tri ci-dessous doit être améliorée
  ...
  /* le code suivant est basé sur l'algorithme de Knuth;
     pour plus de détails consulter le livre The Art of
     Computer Programming, vol. 4A */
  ...