Javadoc

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 BocchiUltimo 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 funzione@author <descrizione autore> Genera una voce "autore". Si possono avere più tag

@author consecutivi, uno per ogni autore.@version <descrizione versione> Genera una voce "versione".

Esempio

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

*/public class Frazione{............}


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


*/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 funzione@param <nome parametro> <descrizione> 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.

@return <descrizione> Aggiunge una sezione "return" al metodo con la descrizione del valore restituito. La descrizione può estendersi su più righe.

@throws <classe> <descrizione> Aggiunge una nota che indica che il metodo può generare un'eccezione. Classe è la classe alla quale appartiene l'eccezione.

Esempio



3

*/public class Frazione{

/**Costante numerica 2

*/public static final DUE= 2;/**

Crea una frazione con numeratore e denominatorespecificati.@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

*/public double dividiFrazioni(double fraz1,double fraz2) throws ArithmeticException{.........}}

Commenti generali

I seguenti tag possono essere utilizzati per i commenti alle classi, ai campi o ai metodi, indifferentemente.

@since@deprecated@see

sintassi funzione@since <testo> Genera una voce "da" . Il testo contiene la descrizione della

versione che ha introdotto questa funzione per la prima volta.

@deprecated <testo> 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.

@see <collegamento> Aggiunge un collegamento ipertestuale o un testo nella sezione "see also" (vedi anche). Più tag @see per un metodo devono essere tenuti insieme.

@link <collegamento> 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>


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.1Questa 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.


5

Primo passoAccertarsi che la variabile d'ambiente di sistema path contenga il percorso che conduce alla directory bin del JDK.

Secondo passoCreare, 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 passoAndare 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 passoPosizionarsi nella directory contenente i file sorgente che si desidera documentare. Supponiamo che tale directory siaC:\sourceDir

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 nomePackage1 nomePackage2 ...

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.


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

comandocd 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.


7

Javadoc

Documents

Transcript of Javadoc