Java: documentazione con javadoc

La documentazione HTML di una classe Java può essere realizzata mediante un utile tool sviluppato in JDK ovvero javadoc. La stessa documentazione in linea di Java non è altro che il risultato generato da javadoc sulle librerie di Java. Per realizzare una buona documentazione occorre allora conoscere i tag usati dal tool, sono inoltre permessi i tag HTML (ad esempio: code, strong, em etc... etc...).

Ogni commento nella forma /** ... */ che precede una classe, un metodo oppure un campo dell'istanza viene riportato da javadoc nella documentazione in linea. E' in questi commenti che il programmatore deve spiegare le ragioni e le utilità di certi metodi.

Alcuni tag possono poi essere inseriti all'interno dei commenti per arricchire la documentazione. Con il tag @param variabile descrizione è possibile fornire una descrizione per la variabile usata! Con il tag @return descrizione, invece, è possibile riportare nella documentazione una descrizione del valore ritornato da un metodo. Se un metodo di una classe è in grado di generare un'eccezione si può segnalare l'evento all'interno del sorgente con il tag @throws classe descrizione.
Altri tag sono @author nome_autore e @version descrizione_versione che aggiungono, rispettivamente, alla documentazione informazioni sull'autore e sulla versione della classe.

Con il comando javadoc -d nomeDirectory nomePackage oppure javadoc -d nomeDirectory nomeClasse viene generata, nella cartella nomeDirectory, la documentazione di un package o della classe. Non dimenticate di omettere l'opzione -d, in tal caso la documentazione verrà generata nella stessa cartella che ospita il file sorgente!