Commenti di documentazione: Javadoc

L'importanza della documentazione

La soluzione di un problema informatico non pu limitarsi alla semplice stesura di un programma, bens il software applicativo deve essere il risultato finale di un lavoro di analisi del problema e di studio della soluzione. La documentazione prodotta durante la fase di analisi risulta fondamentale per il lavoro di programmazione; essa permette, infatti, di raggiungere due obiettivi importanti: far comprendere il lavoro svolto a persone diverse da quelle che hanno collaborato al progetto; riuscire a comprendere il lavoro realizzato anche a distanza di tempo, soprattutto per consentire interventi di manutenzione (modifiche, ampliamenti, ecc.). In particolare, nella programmazione orientata agli oggetti, la produzione di documentazione diventa una necessit: ogni classe che fa parte del progetto deve fornire informazioni riguardanti la sua interfaccia pubblica, pena l'impossibilit per gli utenti (programmatori) di utilizzare le classi.

Il tool Javadoc
Il problema pi grande che si incontra producendo la documentazione di mantenerla aggiornata. Se la documentazione e il codice sono separati, diventa difficoltoso cambiare la documentazione ogni volta che si cambia il codice. Java offre una soluzione molto semplice: tenere insieme codice e documentazione all'interno dello stesso file. La documentazione pu essere inserita nel codice utilizzando i commenti di documentazione, cio commenti multilinea che iniziano con i simboli /** e terminano con i simboli */. I commenti di documentazione vengono poi estratti eseguendo l'utility javadoc (distribuito con il JDK), il quale genera la documentazione in un formato standard, identico a quello utilizzato per tutta la documentazione ufficiale di Java. I file prodotti in output da javadoc sono file HTML e quindi possibile visualizzarli con un qualsiasi browser Web.

Inserimento dei commenti di documentazione

L'utility javadoc estrae documentazione per i seguenti elementi: package; classi e interfacce pubbliche (dichiarate con lo specificatore public); metodi pubblici e protetti (dichiarati con gli specificatori public o protected); campi pubblici e protetti (dichiarati con gli specificatori public o protected). Ogni commento di documentazione viene inserito immediatamente sopra la funzione che descrive.

Autore: Cinzia Bocchi Ultimo aggiornamento: 16/10/11

Esempio /** Un commento di classe */ public class docTest { /** Un commento di variabile */ public int i; /** Un commento di metodo */ public void f() {...} }

Contenuto dei commenti di documentazione

Ogni commento di documentazione contiene: testo formattato liberamente; tag doc. Nel testo libero possibile inserire tag HTML, ad eccezione dei titoli <hn> e dei righelli <hr> perch potrebbero interferire con la formattazione del documento. I tag doc sono comandi che iniziano con @ e che sono posti all'inizio di una linea.

Commenti alle classi

Il commento a una classe deve essere inserito dopo ogni dichiarazione import, appena prima della definizione di classe. Nel commento ad una classe possono essere inseriti i seguenti tag: @author @version Per ogni tag segue una descrizione della sintassi e della funzione svolta.
sintassi @author <descrizione autore> @version <descrizione versione> funzione Genera una voce "autore". Si possono avere pi tag @author consecutivi, uno per ogni autore. Genera una voce "versione".

Esempio /** @author Rossi Mario @version 1.1 Questa classe fornisce metodi per eseguire calcoli con le frazioni. */ public class Frazione {............}

Autore: Cinzia Bocchi Ultimo aggiornamento: 16/10/11

Commenti ai campi
Il commento a un campo deve essere inserito prima della sua dichiarazione e non prevede l'uso di particolari doc tag; sufficiente inserire la descrizione del campo tra i delimitatori /** e */. Esempio /** @author Rossi Mario @version 1.1 Questa classe fornisce metodi per eseguire calcoli con le frazioni.

*/ public class Frazione { /** Costante numerica 2 */ public static final DUE= 2; .......................... }

Commenti ai metodi
Ogni commento a un metodo deve trovarsi appena prima del metodo che descrive. Si possono utilizzare i seguenti tag: @param @return @throws Per ogni tag segue una descrizione della sintassi e della funzione svolta.
sintassi @param <nome parametro> <descrizione> funzione Genera una voce nella sezione "parametri" del metodo. La descrizione pu estendersi su pi righe. Tutti i tag @param per un metodo devono essere insieme. Aggiunge una sezione "return" al metodo con la descrizione del valore restituito. La descrizione pu estendersi su pi righe. Aggiunge una nota che indica che il metodo pu generare un'eccezione. Classe la classe alla quale appartiene l'eccezione.

@return <descrizione> @throws <classe> <descrizione>

Esempio /** @author Rossi Mario @version 1.1 Questa classe fornisce metodi per eseguire calcoli con le frazioni.

Autore: Cinzia Bocchi Ultimo aggiornamento: 16/10/11

*/ public class Frazione { /** Costante numerica 2 */ public static final DUE= 2; /** Crea una frazione con numeratore e denominatore specificati. @param num il numeratore @param den il denominatore */ public Frazione(double num,double den) {.........} /** Calcola il quoziente della divisione tra due frazioni. @param fraz1 la frazione dividendo @param fraz2 la frazione divisore @return il quoziente della divisione @throws ArithmeticException se il divisore zero fraz1,double fraz2) throws

*/ public double dividiFrazioni(double ArithmeticException {.........} }

Commenti generali
I seguenti tag possono essere utilizzati per i commenti alle classi, ai campi o ai metodi, indifferentemente. @since @deprecated @see
sintassi @since <testo> @deprecated <testo> @see <collegamento> @link <collegamento> funzione Genera una voce "da" . Il testo contiene la descrizione della versione che ha introdotto questa funzione per la prima volta. Aggiunge un commento che dice che la classe, il metodo o il campo, non dovrebbero pi essere utilizzati. E' consigliabile anche suggerire un possibile sostituto. Aggiunge un collegamento ipertestuale o un testo nella sezione "see also" (vedi anche). Pi tag @see per un metodo devono essere tenuti insieme. Inserisce un collegamento ipertestuale in un commento.

Il tag @see Collegamento pu avere la forma: nome package.nome classe [etichetta] nome package.nome classe#nome metodo [etichetta] <a href= "destinazione"> [etichetta] </a>
Autore: Cinzia Bocchi Ultimo aggiornamento: 16/10/11

"testo"

Tutto ci che racchiuso tra parentesi quadrate si intende opzionale.

nome package.nome classe Inserisce un collegamento ipertestuale alla classe <nome classe>. Se la classe si trova nel package corrente, possibile omettere il nome del package. es) @see Frazione

nome package.nome classe#nome metodo Inserisce un collegamento ipertestuale al metodo <nome metodo>. Se il metodo si trova nella classe corrente, possibile omettere il nome del package e il nome della classe. es) @see Frazione#dividiFrazioni(double,double)

<a href= "destinazione"> </a> Inserisce un collegamento ipertestuale a destinazione. La destinazione pu anche essere un URL. es) @see <a href= "HomePage.html"> </a> Nei tre casi precedenti possibile specificare un'etichetta che apparir come ancora del collegamento. Se si omette l'etichetta, l'utente vedr come ancora il nome del codice di destinazione o l'URL. "testo" Aggiunge il testo racchiuso tra virgolette nella sezione see also. es) @see "Capitolo 2 del libro di testo" Il tag @link Il tag @link ha la stessa sintassi del tag @see, ma consente di inserire un collegamento ipertestuale in qualsiasi commento. es) /** @author Rossi Mario @version 1.1 Questa classe fornisce metodi per eseguire calcoli con le frazioni. Vedere @link Mate.Calcolo Matematica */ public class Frazione {............}

Commenti ai package
Per generare commenti ai package necessario aggiungere un file chiamato package.html in ogni directory di package; tutto il testo compreso tra i tag HTML <body> e </body> viene estratto da javadoc.

Estrazione dei commenti di documentazione

Per estrarre i commenti occorre lanciare l'utility javadoc. In seguito descritta la procedura da seguire in ambiente Windows, in cinque passi.
Autore: Cinzia Bocchi Ultimo aggiornamento: 16/10/11

Primo passo Accertarsi che la variabile d'ambiente di sistema path contenga il percorso che conduce alla directory bin del JDK. Secondo passo Creare, se non esiste gi, una directory in cui si desidera che siano salvati i file HTML contenenti la documentazione. Supponiamo che il nome di tale directory sia C:\Programmi\Java\jdj1.6.0\docDir. Terzo passo Andare al prompt del DOS selezionando dal menu di avvio Programmi\Accessori\Prompt di comando (o qualcosa di simile, a seconda del sistema operativo usato). In alternativa, cercare il comando cmd.exe ed eseguirlo. Quarto passo Posizionarsi nella directory contenente i file documentare. Supponiamo che tale directory sia C:\sourceDir sorgente che si desidera

Per posizionarci nella directory sourceDir digitiamo il comando cd C:\sourceDir

al prompt del DOS e poi premiamo invio. Quinto passo Eseguire il comando javadoc -d Programmi\Java\jdj1.6.0\docDir nomePackage

se si vuole estrarre i commenti da un solo package, oppure javadoc -d Programmi\Java\jdj1.6.0\docDir nomePackage2 ... nomePackage1

per documentare pi package. Se i file si trovano nel package predefinito (.) eseguire invece javadoc -d Programmi\Java\jdj1.6.0\docDir *.java

Se si omette l'opzione -d, i file HTML vengono estratti nella directory corrente, cio in sourceDir. Altre opzioni utilizzabili con javadoc sono -author e -version per includere nella documentazione i tag @author e @version, poich per default non sono inclusi. Javadoc crea nella directory docDir, diversi file HTML. Per accedere all'indice principale, aprire il file index.html.
Autore: Cinzia Bocchi Ultimo aggiornamento: 16/10/11

Una procedura di estrazione semplificata (package predefinito)

Quando non definiamo un package per una classe, questa appartiene al package predefinito (indicato con un punto .). Supponiamo che i file Java da cui vogliamo estrarre la documentazione si trovino nel package predefinito, allinterno della cartella C:\myjava. Per estrarre i commenti: 1. creiamo una cartella doc allinterno di C:\myjava; 2. andiamo al prompt del DOS e posizioniamoci nella cartella myjava con il comando cd C:\myjava 3. lanciamo javadoc con il comando javadoc -d doc *.java

se vogliamo estrarre la documentazione per tutti i file java presenti nella cartella, oppure con javadoc -d doc MiaClasse.java

se vogliamo estrarre i commenti per la sola classe MiaClasse.

Quest'opera stata rilasciata con licenza Creative Commons Attribution-ShareAlike 3.0 Unported. Per leggere una copia della licenza visita il sito web http://creativecommons.org/licenses/by-sa/3.0/ o spedisci una lettera a Creative Commons, 171 Second Street, Suite 300, San Francisco, California, 94105, USA.
Autore: Cinzia Bocchi Ultimo aggiornamento: 16/10/11