Javadoc: differenze tra le versioni

Versione delle 17:18, 3 feb 2007

Versione delle 17:23, 3 feb 2007

Riga 1:

'''Javadoc''' è un [[applicazione|applicativo]] incluso nel kit di sviluppo [[Java (linguaggio)|Java]] della [[Sun Microsystems]], utilizzato per la generazione automatica della documentazione del [[Codice (informatica)|codice sorgente]].

== Storia ==

''JavaDoc'' nacque come toolstrumento 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 [[motore di ricerca|motori di ricerca]]. Tuttavia, la creazione e manutenzione di una tale mole di pagine [[World Wide Web|web]] non sarebbe stata pensabile senza l'aiuto di un sistema automatico: basti pensare alla quantità di riferimenti incrociati che ci sono fra le [[classe (informatica)|classi]] ([[ereditarietà (informatica)|ereditarietà]] fra classi, firme dei metodi, riferimenti a ''[[package (Java)|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:

Riga 10:

* 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 toolstrumenti 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]], [[Microsoft Word|Word]], [[Rich Text Format|RTF]], [[Microsoft Help]], [[LaTeX]], ecc.

Il grande successo di JavaDoc è dovuto alla possibilità di poter 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, che è appuntocioè 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 [[Application Programming Interface|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 deidi '«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, ecco alcuni esempi:

* @param, @return, @throws : documentazione relativa a parametri, valori di ritorno ed eccezioni di un metodo;

* @deprecated : (vedere sopra) indica che l'elemento potrà essere eliminato da una versione successiva del software;