• l’insieme di pagine HTML che accompagna il Java Development Kit sin dalla sua prima versione è voluminoso quanto dettagliato, indispensabile per orientarsi in una collezione di package sempre più numerosa ed articolata;
• javadoc, lo strumento utilizzato da Sun per produrre la documentazione ufficiale di cui sopra, viene incluso in JDK e di conseguenza distribuito gratuitamente. In particolare, javadoc è presente a partire da JDK 1.1, ma non riporta una propria versione, riconoscibile in modo indipendente perché specificata nell’eseguibile o nel package di riferimento: la consuetudine è quella di indicare a questo scopo la stessa versione del JDK nel quale è contenuto (quindi, ad esempio, Java 2 SDK versione 1.2.2 contiene javadoc versione 1.2.2).

Come si comporta e cosa può fare javadoc? In termini generali, lo strumento messo a disposizione da Sun elabora le dichiarazioni e i commenti doc presenti in uno o più file sorgenti Java, producendo un set corrispondente di pagine HTML che descrivono classi, interfacce, costruttori, metodi e campi con indicatori di visibilità public o protected.
In pratica, javadoc è in grado di riproporre, in un formato facilmente consultabile, lo “scheletro” delle dichiarazioni interne al codice sorgente, completamente spogliato delle complicazioni, in questo caso superflue, dell’implementazione.
Non solo: al fine di rendere l’implementazione davvero inutile per l’utilizzatore che intende interfacciarsi con l’insieme di classi in questione, il programmatore è tenuto ad arricchire tale scheletro con chiarimenti, precisazioni ed esempi d’uso. Possiamo definire con l’espressione “commenti doc” gli elementi che consentono di ottenere tale risultato.

Commenti doc
Come noto, Java supporta sia i commenti multilinea (caratteristici di C), delimitati da /* e */, che i commenti monolinea (caratteristici di C++), indicati da //. Entrambi i commenti appartenenti a queste due categorie, definibili come commenti ordinari, vengono inseriti all’interno del codice sorgente Java con lo scopo di rendere più comprensibili i dettagli implementativi del codice stesso.

Il fattore che assume maggiore rilevanza nel contesto di questo articolo è però un terzo tipo di commento, quello che abbiamo già indicato come commento doc e che viene utilizzato da javadoc per integrare la documentazione dell’API di ogni applicazione.

I commenti doc iniziano con /** (invece del normale /*), terminano con */ e sono solitamente multilinea. Vengono inseriti nel codice sorgente, e sono riconosciuti e processati da javadoc solo se immediatamente precedenti la dichiarazione di una qualunque entità (classe, interfaccia, metodo, costruttore, campo).
Ogni commento doc è formato da due sezioni:

• la descrizione, che inizia dopo il delimitatore iniziale /** e prosegue fino alla sezione dei tag;
• la sezione dei tag, la quale inizia con il primo carattere @ che si trova in testa ad una riga (escludendo asterischi e spazi).

I commenti doc sono scritti in HTML. E’ vivamente sconsigliato l’utilizzo di tag HTML strutturali, come ad esempio <H1>, <H2> o <HR>, i quali potrebbero interferire negativamente con la struttura della pagina HTML già predisposta da javadoc.

Di seguito sono riportati alcuni esempi.

Esempio 1 - Commento doc con una sola sezione, su una sola linea

/** Sezione descrittiva del commento doc */

/**
* Sezione descrittiva del commento doc
*/

/**
* Sezione descrittiva del commento doc
*
* @tag Commento per il tag
*/

• la prima riga rientra rispetto al margine in modo da essere allineata con il codice che segue il commento doc. Inizia con /**;
• le righe successive iniziano con * (asterisco) e rientrano di uno spazio ulteriore per allineare gli asterischi;
• è preferibile inserire una riga vuota tra la descrizione e la sezione dei tag, e tra bocchi di tag logicamente correlati;
• ’ultima riga inizia con */.

Qualunque sia la forma scelta tra quelle appena presentate, durante l’elaborazione dei commenti doc ogni asterisco iniziale di riga viene eliminato, così come ogni spazio o tab che lo precede. E’ inoltre preferibile non avere righe eccedenti la lunghezza di 80 caratteri.
Infine, eventuali paragrafi interni al commento doc risultano più facilmente individuabili se separati tramite il tag HTML <p>.

Javadoc duplica i commenti doc di metodi che implementano o che effettuano l’override di altri metodi. Ad esempio, se il metodo mioMetodo1() in una certa classe o interfaccia non ha alcun commento doc, javadoc utilizza il commento doc di mioMetodo2(), che mioMetodo1() implementa o di cui effettua l’override. Quanto detto si verifica quindi in tre situazioni:

• quando un metodo in una classe effettua l’override di un metodo in una superclasse;
• quando un metodo in una interfaccia effettua l’override di un metodo in una delle interfacce da cui eredita;
• quando un metodo in una classe implementa un metodo in una interfaccia.

Come già anticipato, esiste un insieme di tag speciali che, se inseriti all’interno di un commento doc, javadoc riconosce ed elabora. Ognuno di questi tag comincia con @ e deve trovarsi all’inizio di riga, fatta eccezione per eventuali spazi o simboli di asterisco che possono precederlo.

Di seguito si trovano alcuni tra i tag più interessanti (con i relativi argomenti), accompagnati da una breve descrizione.

@author [nome]
Aggiunge “Author:” seguito dal nome specificato.
Ogni commento doc può contenere molteplici tag @author, presentati in ordine cronologico.

@version [versione]
Aggiunge “Version:” seguito dalla versione specificata.

@param [nome del parametro] [descrizione]
Aggiunge il parametro specificato e la sua descrizione alla sezione “Parameters:” del metodo corrente. Il commento doc riferito ad un certo costruttore o ad un certo metodo deve obbligatoriamente presentare un tag @param per ognuno dei parametri attesi, nell’ordine in cui l’implementazione del costruttore o del metodo specifica i parametri stessi.

@return [descrizione]
Aggiunge “Returns:” seguito dalla descrizione specificata. Indica il tipo restituito e la gamma di valori possibili.
Può essere inserito solamente all’interno del codice sorgente Java, dove deve essere obbligatoriamente usato per ogni metodo, a meno che questo non sia un costruttore oppure non presenti alcun valore di ritorno (void).

@throws [nome completo della classe] [descrizione]
Aggiunge “Throws:” seguito dal nome della classe specificata (che costituisce l’eccezione) e dalla sua descrizione. Il commento doc riferito ad un certo costruttore o ad un certo metodo deve presentare un tag @exception per ognuna delle eccezioni che compaiono nella sua clausola throws, presentate in ordine alfabetico.

@see [riferimento]
Aggiunge “See Also:” seguito dal riferimento indicato.

@since [versione]
Utilizzato per specificare da che momento l’entità di riferimento (classe, interfaccia, metodo, costruttore, campo) è stata inserita nell’API.

Figura 2 - Esempio di pagina HTML costruita da javadoc. 
Il file sorgente Java utilizzato ha commenti doc al suo interno

Funzionamento
Uno dei punti di forza del meccanismo ideato da Sun è probabilmente costituito dal fatto che, al fine di realizzare le proprie elaborazioni, javadoc si basa sulla presenza del compilatore javac. In particolare, javadoc utilizza javac per compilare il codice sorgente, con lo scopo di mantenere le dichiarazioni ed i commenti doc, scartando tutte le parti di implementazione. Così facendo viene appunto costruito quello scheletro al quale si è già accennato in precedenza e che risulta appunto essere la base delle pagine HTML di output.

Ciò significa che, in teoria, sarebbe possibile far lavorare javadoc già dalle fasi di design, nel momento in cui l’interfaccia inizia a prendere corpo ma è ancora assente l’implementazione nella sua totalità.
Tale accorgimento moltiplica i vantaggi se adottato all’interno di un gruppo di lavoro costituito da più individui, soprattutto per i programmatori eventualmente assegnati alla scrittura della parte client: esiste chiarezza sin dal primo istante in merito all’interfaccia che andranno ad interrogare.
Il concetto può essere illustrato considerando come esempio un’ipotetica applicazione Java-CORBA, per la quale è norma che chi interroga gli oggetti remoti sia interessato solamente all’interfaccia esposta e non all’implementazione. In questo caso, lo sviluppatore che scrive tali oggetti remoti ha la possibilità di produrre la documentazione completa delle API non appena terminata la fase di compilazione del file IDL, consegnando a chi si occupa di scrivere il codice di interrogazione tutto ciò di cui questi necessita per iniziare la propria opera (in un formato più leggibile rispetto al linguaggio IDL).

L’utilizzo di javac da parte di javadoc è garanzia di produzione di documentazione il più esatta ed affidabile possibile: l’esempio più significativo da questo punto di vista è la creazione del costruttore di default da parte di javac e la sua conseguente presenza nella documentazione HTML, anche nel caso in cui tale costruttore non venga indicato esplicitamente dal programmatore nel codice sorgente.

Dati i meccanismi di funzionamento appena descritti, javadoc può essere sfruttato solo con riferimento a codice Java e non ad altri linguaggi di programmazione.
 
 
 

Utilizzo
Se consideriamo l’aspetto pratico, javadoc viene lanciato da linea di comando nel seguente modo:

 javadoc [opzioni] [package] [file sorgenti] [@mieifile]

L’ordine degli argomenti non è rilevante; questo il loro significato:

• opzioni: le opzioni possibili sono numerose, le più interessanti (con i relativi argomenti) sono
• public, che mostra nella documentazione solamente classi, metodi e campi con modificatore di visibilità public;
• protected, che mostra nella documentazione solamente classi, metodi e campi con modificatore di visibilità protected e public (questa è l’opzione di default);
• package, che mostra nella documentazione solamente classi, metodi e campi con modificatore di visibilità package, protected e public;
• private, che mostra nella documentazione tutte le classi, i metodi e i campi;
• doclet [nome della classe], che specifica la classe del doclet che si intende utilizzare al posto dello standard doclet;
• 1.1, che genera la documentazione con l’aspetto e le funzionalità della documentazione prodotta da javadoc 1.1;
• sourcepath [locazione dei sorgenti], che specifica il percorso per raggiungere i file sorgenti Java quando, dopo il comando javadoc, è presente l’argomento [package];
• classpath [locazione delle classi (classpath)], che specifica il percorso per raggiungere le classi Java;
• J[opzione java], che passa l’argomento indicato direttamente alla Java Virtual Machine;
• d [nome della directory], che specifica, in modo assoluto oppure relativo, la directory di destinazione nella quale javadoc salva i file HTML generati;
• version, che permette di processare il tag @version nella documentazione generata;
• author, che permette di processare il tag @author nella documentazione generata;
• link [url], il quale specifica un URL verso un set di documentazione che, prodotto da javadoc in un momento precedente l’esecuzione corrente, si vuole rendere raggiungibile dalle pagine che javadoc si appresta a generare;

 
• package: un elenco di nomi di package, separati da spazi. E’ necessario indicare nello specifico ognuno dei package che si intende documentare, qualificandolo con il nome completo e senza la possibilità di utilizzare wildcard come * (asterisco);

 
• file sorgenti: un elenco di nomi di file sorgenti Java, separati da spazi, ognuno dei quali può iniziare con un path e contenere wildcard come * (asterisco);

 
• @mieifile: un tag che specifica uno o più file i quali contengono nomi di package e nomi di file sorgenti Java, in qualunque ordine, uno per ogni riga. Javadoc tratta il contenuto dei file indicati come se ogni singola riga si trovasse direttamente su linea di comando.

Fonti
Javadoc è in grado di produrre output a partire da quattro diverse possibili fonti. La prima di queste è il codice sorgente Java, già ampiamente trattato nel corso dell’articolo, dominante sulle altre fonti in termini qualitativi e quantitativi. Ad esso si possono aggiungere:

• file di commento ai package, che javadoc provvede ad includere nella pagina di descrizione del package da lui stesso generata. Il file di commento ad un package deve avere nome package.html (uguale per tutti i package) ed essere posizionato nella directory del package, la medesima che contiene i file sorgenti Java. Il contenuto di package.html è un unico, ampio commento doc, scritto in HTML, il quale non presenta i separatori caratteristici /** e */, e nemmeno l’asterisco in testa ad ogni riga.;
• file di commento generale, che javadoc provvede ad includere nella pagina di descrizione generale da lui stesso creata. Il file di commento generale ha solitamente nome overview.html ed è di norma posizionato nella più “alta” directory interna al percorso contenente i file sorgenti Java (nessuna di queste due disposizioni è obbligatoria).Il contenuto del file di commento generale è un unico, ampio commento doc, scritto in HTML, con le stesse caratteristiche appena viste per package.html;
• file diversi non processati che si ritiene opportuno includere nella documentazione, e rendere quindi raggiungibili dalle pagine HTML generate da javadoc: è il caso, ad esempio, di file con immagini, di file sorgenti Java (.java) con esempi, di file Java compilati (.class) o anche di file HTML il cui contenuto potrebbe essere troppo esteso per un normale commento doc. I file in questione devono essere inseriti in una directory chiamata doc-files, la quale può essere subdirectory di una qualunque directory di package. E’ prevista l’esistenza di una directory doc-files per ogni package, e i nomi dei file devono essere esplicitamente indicati all’interno dei commenti doc di riferimento. Javadoc non esamina il contenuto di doc-files, limitandosi a copiarlo nella corretta directory di destinazione.

Doclet
Javadoc ha un comportamento di default ben preciso, assegnato ed applicato da Sun tramite quello che viene definito standard doclet. Esso stabilisce che venga generata documentazione in formato HTML, la maggior parte della quale è costituita da file che hanno lo stesso nome (con diversa estensione) delle classi o delle interfacce specificate. A queste pagine HTML se ne aggiungono altre la cui denominazione è slegata dal contenuto del codice sorgente e tra le quali possiamo citare, ad esempio, package-summary.html (una per ogni package documentato), overview-summary.html (una per l’intero insieme dei package documentati), deprecated-list.html (una per tutte le voci deprecate) e così via.

Come è facile immaginare, Sun non si limita ad imporre lo standard doclet come strumento di modellazione dell’output di javadoc, ma consente di personalizzarne il contenuto e il formato tramite l’utilizzo dei cosiddetti doclet
I doclet sono veri e propri programmi scritti in Java, i quali utilizzano l’API doclet al fine di specificare il contenuto e il formato dell’output di javadoc. Il programmatore ha, a questo scopo, sia la facoltà di scrivere classi completamente nuove, sia la possibilità di modificare lo standard doclet.
Le classi che costituiscono l’API doclet si trovano nel file lib/tools.jar all’interno di JDK.

Nel corso di questo articolo alcuni argomenti non hanno purtroppo trovato lo spazio e il livello di dettaglio che meriterebbero. In particolare, i tag inseribili nei commenti doc, le opzioni e i file generati da javadoc, la sezione doclet potrebbero essere ulteriormente approfonditi per ottenere uno sfruttamento ottimale delle capacità che Sun ha fornito a javadoc.
Quanto illustrato è comunque nel complesso ampiamente sufficiente per avvicinarsi allo strumento javadoc e considerare senza dubbio la documentazione dell’API come parte integrante e rilevante di ogni applicazione o insieme di classi, e non come un semplice accessorio opzionale.
 
 

Esempi
Esempio 4 - Codice sorgente
Viene presentato il codice del file MiaClasse.java, processato con javadoc per ottenere la pagina HTML di figura 2.

 package miopackage;

 /**
  * Classe di esempio.
  * @author Manzini Matteo
  * @version 1.0
  */
 public class MiaClasse {

  /**
   * Variabile di tipo int
   */
   public int miaVariabile01;

  /**
   * Variabile che contiene la rappresentazione della classe
   */
   private String miaVariabile02 = "public class MiaClasse";

  /**
   * Costruttore che inizializza miaVariabile01
   * @param mioParametro il valore per inizializzare miaVariabile01
   */
   public MiaClasse(int mioParametro) {
     miaVariabile01 = mioParametro;
   }

  /**
   * Restituzione del valore di miaVariabile01
   * @return il valore di miaVariabile01
   */
   public int getMiaVariabile01() {
     return miaVariabile01;
   }

  /**
   * Rappresentazione della classe
   * @return il valore di miaVariabile02
   */
   public String toString() {
     return miaVariabile02;
   }
 }

Di seguito i passi da compiere per riprodurre la documentazione di alcune classi del JDK. Per tutti gli esempi della sezione corrente valgono le seguenti supposizioni:

• locazione dei file sorgenti Java: C:\home\src\java\util\*java;
• directory di destinazione: C:\home\html.

Esempio 5 - Documentazione di uno o più package
Al fine di documentare un package nel suo insieme è necessario che i file sorgenti in esso contenuti si trovino in una directory chiamata come il package stesso. Nel caso di nome di package composto da molteplici elementi separati da punti, ognuno di questi elementi rappresenta una diversa directory (ad esempio, alla classe Vector del package java.util deve corrispondere il file \java\util\Vector.java).
In questo caso è possibile eseguire javadoc in uno dei seguenti modi:
· muovendosi nella directory superiore alla più alta tra le directory che rappresentano il package in questione e lanciando javadoc con le opzioni e gli argomenti appropriati. Esempio:

 C:> cd c:\home\src
 C:\home\src> javadoc -d C:\home\html java.util

· lanciando javadoc da qualunque directory, con le opzioni e gli argomenti appropriati. Esempio:

 C:> javadoc -d C:\home\html -sourcepath C:\home\src java.util

Sia nel primo che nel secondo caso viene generata documentazione in formato HTML per le classi e le interfacce public e protected dell’intero package java.util. La documentazione viene salvata nella directory di destinazione specificata (C:\home\html).

Esempio 6 - Documentazione di una o più classi
E’ possibile utilizzare il carattere * (asterisco) per indicare gruppi di classi.
In questo caso si può eseguire javadoc in uno dei seguenti modi:

• muovendosi nella directory contenente i file sorgenti Java e lanciando javadoc con le opzioni e gli argomenti appropriati. Esempio:

 

 
 
 

C:> cd C:\home\src\java\util
C:\home\src\java\util> javadoc -d C:\home\html Date.java Hash*.java

• muovendosi nella directory superiore alla più alta tra le directory che rappresentano il o i package in questione e lanciando javadoc con le opzioni e gli argomenti appropriati. Esempio:

 

 
 
 

C:> cd c:\home\src
C:\home\src> javadoc -d C:\home\html java\util\Date.java java\awt\Button.java

• lanciando javadoc da qualunque directory, con le opzioni e gli argomenti appropriati. Esempio:

 

 

C:> javadoc -d C:\home\html C:\home\src\java\util\Vector.java

Nel primo caso viene generata documentazione in formato HTML per la classe java.util.Date e per tutte le classi del package java.util il cui nome inizia con Hash.
Nel secondo caso viene generata documentazione in formato HTML per le classi java.util.Date e java.awt.Button.
Nel terzo caso viene generata documentazione in formato HTML per la classe java.util.Vector.

Esempio 7 - Documentazione di package e classi
In questo caso (che riprende gli esempi precedenti, documentando package e classi allo stesso tempo) è possibile eseguire javadoc lanciando javadoc con le opzioni e gli argomenti appropriati. Ad esempio:

C:> javadoc -d C:\home\html -sourcepath C:\home\src java.util C:\home\src\java\awt\Button.java

Viene qui generata documentazione in formato HTML per tutte le classi del package java.util e per la classe java.awt.Button.
 
 
 

Bibliografia e risorse

• David Flanagan “Java In A Nutshell, 3rd Edition”, O’Reilly;
• “Javadoc Tool Home Page” - http://java.sun.com/j2se/javadoc/;
• “Javadoc FAQ” - http://java.sun.com/j2se/javadoc/faq.html;
• “How to Write Doc Comments for Javadoc” 

http://java.sun.com/j2se/javadoc/writingdoccomments/index.html;
• “Javadoc - The Java API Documentation Generator” 

http://java.sun.com/j2se/1.3/docs/tooldocs/win32/javadoc.html;
• “Doclet Overview” - http://java.sun.com/j2se/1.3/docs/tooldocs/javadoc/overview.html;
• “What’s New in Javadoc 1.2”

 http://java.sun.com/products/jdk/1.2/docs/tooldocs/javadoc/whatsnew.html;
• “What’s New in Javadoc 1.3” - http://java.sun.com/j2se/1.3/docs/tooldocs/javadoc/whatsnew-1.3.html.