Lezione 11:

DOCUMENTAZIONE DEL CODICE JAVA

Javadoc

Java fornisce un meccanismo automatico per generare la documentazione in formato HTML (pagine WEB) dei sorgenti. Estrae la documentazione dal codice java e dai commenti scritti nel programma, basandosi su alcune regole di sintassi che il programmatore deve seguire nello scrivere il codice e i commenti.

Il comando e' "javadoc" e si esegue sul file sorgente, esempio:

  javadoc Rectangle.java

Che cosa viene documentato

• Le classi o interfacce esplicitamente dichiarate come pubbliche o protette.

  Quindi scrivere sempre "public" davanti a una classe (es. "public class MiaClasse" e non semplicemente "class MiaClasse").

• In una classe, costruttori, metodi, attributi che siano stati dichiarati esplicitamente come pubblici o protetti.

  In generale e' buona norma scrivere sempre la visibilita' (public, protected o private) di costruttori, metodi, attributi. A maggior ragione e' qui necessario scrivere sempre "public" o "protected" davanti a cio' che vogliamo che appaia nella documentazione.

• Le classi interne pubbliche o protette dichiarate con un nome, non senza nome.

  Sono classi con un mome quelle definite con:
     public class MiaClasseInterna
      { ... }
  dentro ad un'altra classe (es. NegativeRectangleException nella lezione 5).

  Sono classi senza nome quelle definite mentre si crea un oggetto, noi l'abbiamo visto nel caso degli event listener:
     ActionListener pippo = new ActionListener()
      { public void ActionPerformed(ActionEvent e)
         { ... }
      };
  

La politica di documentare solo il pubblico o il protetto rispecchia l'idea che la documentazione e' rivolta a chi vuole usare la classe a scatola chiusa (public) o per derivarne sottoclassi (protected), non a chi vuole sapere come funziona la classe internamente per eventualmente modificare il codice.

Come scrivere i commenti

Commenti su piu' linee:

/**
 * This is the typical format of a simple documentation comment
 * that spans two lines.
 */

I commenti vanno messi:

• quelli relativi a una classe o un'interfaccia, immediatamente prima dell'inizio della dichiarazione della classe o interfaccia (cioe' subito prima delle parole chiave "class..." o "interface...")
• quelli relativi a un metodo, immediatamente prima della dichiarazione del metodo
• quelli relativi a un attributo, immediatamente prima della dichiarazione della variabile
• e non dichiarare due variabili sulla stessa riga (es. non scrivere "int x, y;" ma "int x;" e "int y;" ciascuna preceduta dal suo commento)

Nei commenti posso scrivere:

• testo
• testo con tag (marcature) del linguaggio HTML, ad esempio per produrre scritte in grassetto (<B>importante</B>) o per richiamare altre pagine web (<A HREF="http://www.disi.unige.it/">pagina del DISI</A.>)
• riferimenti incrociati ad altre parti della documentazione di questa classe o di un'altra (preceduti dalla parola chiave "@see")
• per i metodi, spiegazione a parte dei valori dei parametri (parola chiave "@param") e del risultato (parola chiave "@return")

Nota: Tutti i commenti, dovunque scritti, che non rispettano la sintassi javadoc vengono ignorati, ma possono ugualmente essere utili per chi legge il codice.

Esempio / Facsimile

/* importante gli "import" vanno messi prima del commento sulla classe,
in questo caso non serviva ma l'ho messo come esempio (questo commento
non e' scritto secondo la sintassi javadoc e sara' ignorato) */
import java.io.*;

/**
 *Commenti generali sulla classe MiaClasse, una classe completamente idiota.
 */
public class MiaClasse
{
 /**
  * Commenti sulla variabile miaVariabile, un intero qualsiasi.
  * Notare il riferimento incrociato al metodo mioMetodo...
  * @see MiaClasse#mioMetodo
  */
  protected int miaVariabile;

 /**
  * Commenti sul metodo mioMetodo, assegna il valore di miaVariabile.
  * Notare che ho commentato i parametri e il valore di ritorno...
  * @param     x  il numero che volete assegnare a miaVariabile
  * @param     y  un altro numero che non serve a niente
  * @return    il numero x appena assegnato, tale e quale
  */
  public int mioMetodo(int x, int y)
  { miaVariabile = x; return x; }

  /**
   * Commenti sul costruttore, costruisce oggetto con miaVariabile a zero.
   */
  public MiaClasse()
  { miaVariabile = 0; }
}

Provare ad eseguire:
   javadoc MiaClasse.java
Questo produce vari file HTML tra cui uno chiamato MiaClasse.html che corrisponde alla pagina di documentazione di questa classe.

Riferimento

Maggiori informazioni in rete all'indirizzo: http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/javadoc.html