Si possono documentare facilmente le classi usando l’utility javadoc.
I commenti devono essere inseriti nello stile javadoc cioè compresi tra /** e */
Il contenuto di questi commenti viene estratto da javadoc direttamente dal codice sorgente e usato per generare automaticamente la documentazione in formato HTML (quindi la documentazione si può esaminare con un browser).
I collegamenti ipertestuali ai metodi e alle sottoclassi vengono creati automaticamente.
Si possono incorporare nei commenti tag HTML per formattare i commenti o aggiungere immagini.
I commenti possono essere di classe, attributo o metodo. Un commento di classe compare subito prima della definizione della classe, un commento di attributo subito prima della definizione della variabile di istanza e un commento di metodo subito prima della definizione del metodo. Javadoc elabora i commenti solo per attributi e metodi public o protected.
Per ogni classe bisogna indicare una breve spiegazione all’inizio della classe.
/** Scopo della classe */
Per ogni attributo (public o protected) bisogna indicare una breve descrizione.
/** Significato dell’attributo */
Per ogni metodo (public o protected) bisogna indicare lo scopo del metodo, poi per ciascun parametro una riga del tipo @param nomeDelParametro descrizione, infine una riga che inizia con @return e descrive il valore restituito.
Nei commenti è opportuno indicare anche le precondizioni che devono essere soddisfatte dai parametri.
/** Scopo del metodo @param nome descrizione @param nome descrizione @return descrizione */
La prima riga (fino al primo punto) viene inserita in una tabella di riepilogo.
I commenti javadoc possono contenere anche altri tag tra cui:
| @author | specifica l’autore; |
| @version | specifica la versione; |
| @see package.class#member | inserisce un collegamento alla documentazione di un’altra classe, attributo o metodo nella sezione “See also:”; |
| {@link package.class#member} | inserisce un collegamento alla documentazione di un’altra classe, attributo o metodo all’interno del testo, nel punto in cui viene usato. |
@author e @version vengono usati solo nel commento della classe (non possono essere usati nei commenti di attributi o metodi).
@see e {@link} possono essere usati in qualsiasi commento.
Un commento di una classe di solito ha una forma del tipo:
/** * Scopo della classe * @version n.n (gg-mm-aaaa) * @author autore * @see AltraClasse1 * @see AltraClasse2 */
Dopo aver scritto i commenti si richiama:
javadoc NomeClasse.java
per creare la documentazione per una classe, oppure:
javadoc nomePackage
per creare la documentazione per tutto il package.
Un’opzione utile è -d directory che permette di specificare la directory in cui memorizzare i file HTML creati.
Documentazione della classe Articolo.
classe Articolo con istruzioni javadoc
Eccezioni e asserzioni
Per ogni metodo, nella documentazione (nel commento @param), dovrebbero essere descritti quali input sono validi, cioè quali precondizioni devono essere soddisfatte.
Il metodo deve verificare se le precondizioni sono soddisfatte e in caso negativo sollevare una eccezione.
In un metodo per il calcolo della radice quadrata la precondizione è che il valore sia positivo.
Invece di usare le eccezioni, per garantire che le precondizioni siano rispettate si possono usare le asserzioni.
