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
[modifica | modifica wikitesto]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
[modifica | modifica wikitesto]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
[modifica | modifica wikitesto]- (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).