|
== Storia ==
''JavadocJavaDoc'' nacque come tool interno utilizzato dai ricercatori della [[Sun Microsystems|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 qualche 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. ''JavadocJavaDoc'' 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 ''JavadocJavaDoc'' è diventò sempre più sofisticato e ricco di funzioni:
* inserimento di link, anche a javadocJavaDoc 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 JavadocJavaDoc 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 tool 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 JavadocJavaDoc è 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 programmazion che è appunto 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 Microsystems|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 dei '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:
Il [[tool]] '''Javadoc''' genera la [[documentazione]] estraendo informazioni direttamente dal [[Codice_(informatica)|codice]] opportunamente commentato.
* @param, @return, @throws : documentazione relativa a parametri, valori di ritorno ed eccezioni di un metodo;
* @deprecated : (v. sopra) indica che l'elemento potrà essere eliminato da una versione successiva del software;
'''JavaDoc''' é un ottimo metodo per la creazione di documentazione [[software]] in quanto il programmatore non deve rivedere tutto il codice per scriverla (il che risulta spesso un'operazione laboriosa) ma scrive la documentazione mentre crea il codice.
* @link: crea un collegamento ipertestuale alla documentazione locale o a risorse esterna (tipicamente internet)
Questa maniera di operare, favorisce sia il programmatore che, scrivendo documentazione insieme al codice ha più chiaro ciò che sta facendo potendo spiegare meglio all'utilizzatore del codice il concetto di quello che il codice fa.
[[Categoria:Java]]
| 