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

1

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

2

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

3

*/ 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

4

"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

5

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

6

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, all’interno della cartella C:\myjava. Per estrarre i commenti: 1. creiamo una cartella doc all’interno 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

7

Sign up to vote on this title
UsefulNot useful