Javadoc

Javadoc è un applicativo incluso nel Java Development Kit della Sun Microsystems, utilizzato per la generazione automatica della documentazione del codice sorgente scritto in linguaggio Java.

Storia

JavaDoc nacque come strumento interno utilizzato dai ricercatori della Sun che stavano lavorando alla creazione del linguaggio Java e delle sue librerie; la grande mole di sorgenti spinse alcuni membri del team a creare un programma per la generazione automatica di documentazione HTML. Questo formato infatti consente una navigazione molto efficace e veloce, è molto conosciuto dai programmatori ed è facilmente indicizzabile dai motori di ricerca. Tuttavia, la creazione e manutenzione di una tale mole di pagine web non sarebbe stata pensabile senza l'aiuto di un sistema automatico: basti pensare alla quantità di riferimenti incrociati che ci sono fra le classi (ereditarietà fra classi, firme dei metodi, riferimenti a package solo per citarne alcuni) e agli inevitabili errori di battitura a cui si va incontro scrivendo documentazione. JavaDoc nacque quindi per permettere ai programmatori di inserire dei frammenti HTML nei commenti (ignorati quindi dal compilatore): già con le prime versioni si potevano inserire le descrizioni di ogni classe e dei suoi metodi, nonché il significato dei parametri e delle variabili membro.

Con il progredire delle versioni JavaDoc diventò sempre più sofisticato e ricco di funzioni:

• inserimento di link, anche a JavaDoc esterni;
• inserimento dell'indicazione @deprecated per segnalare classi e/o metodi destinati a scomparire in future versioni del software;
• opzioni per la formattazione avanzata;
• possibilità di creare le proprie Doclet: estensioni di JavaDoc che permettono di gestire a piacimento le varie fasi di generazione della documentazione

Le Doclet in particolare permisero ad altre case produttrici di software e ad altri sviluppatori (soprattutto open source) di creare strumenti molto diversificati:

• generazione di schemi UML, grafi di dipendenze fra classi e package, analizzatori di codice (molto utilizzati nell'ingegneria del software);
• generazione di documentazione in formato PDF, Word, RTF, Microsoft Help, LaTeX, ecc.

Il grande successo di JavaDoc è dovuto alla possibilità di creare con facilità una documentazione dall'aspetto professionale, del tutto simile a quella ufficiale, anche da parte del principiante, che impara a valorizzare un aspetto spesso sottovalutato della programmazione, cioè la gestione dei documenti relativi ai propri programmi. I file HTML che vengono generati dalla doclet standard infatti hanno la stessa organizzazione grafica e logica della documentazione che Sun fornisce per le API che essa distribuisce.

Funzionamento

Le informazioni di base su package, classi, metodi e campi generate automaticamente possono essere arricchite da ulteriori dettagli per mezzo di «commenti JavaDoc»; questi sono racchiusi fra le sequenze di caratteri /** e */ (di fatto sono una forma particolare di «commento multi-linea»), e vengono aggiunti alla documentazione dell'elemento che li segue. Possono contenere frammenti di HTML e marcatori (o tag) peculiari di JavaDoc.

Lista dei tag di JavaDoc:

Tag	Descrizione
@author	Nome dello sviluppatore.
@deprecated	(vedere sopra) indica che l'elemento potrà essere eliminato da una versione successiva del software.
@exception	Indica eccezioni lanciate da un metodo; cf. @throws.
@link	Crea un collegamento ipertestuale alla documentazione locale o a risorse esterna (tipicamente internet).
@param	Definisce i parametri di un metodo. Richiesto per ogni parametro.
@return	Indica i valori di ritorno di un metodo. Questo tag non va usato per metodi o costruttori che restituiscono void.
@see	Indica un'associazione a un altro metodo o classe.
@since	Indica quando un metodo è stato aggiunto a una classe.
@throws	Indica eccezioni lanciate da un metodo. Sinonimo di @exception introdotto in Javadoc 1.2.
@version	Indica il numero di versione di una classe o un metodo.

NB: Se si vuole il simbolo @ senza l'intenzione di creare un tag di JavaDoc, si può usare il codice HTML @ per evitare problemi in fase di parsing.

Collegamenti esterni

• (EN) Javadoc Tool, su oracle.com.
• (EN) Guida su come scrivere commenti con Javadoc Tool, su oracle.com.
• (EN) MyJavadoc.net (motore di ricerca), su myjavadoc.net. URL consultato il 10 settembre 2018 (archiviato dall'url originale il 24 aprile 2017).