|
'''Javadoc''' è un [[toolapplicazione (informatica)|applicativo]] incluso nel kit di sviluppo [[Java (linguaggio)|JavaDevelopment Kit]] della [[Sun Microsystems|Sun]], utilizzato per la generazione automatica della [[Documentazione del software|documentazione]] del [[Codice (informatica)|codice sorgente]] scritto in [[Java (linguaggio di programmazione)|linguaggio Java]].
== Storia ==
''JavaDoc''Javadoc nacque come toolstrumento 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 deldella teamsquadra 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 qualcheun sistema automatico: basti pensare alla quantità di riferimenti incrociati che ci sono fra le [[classe (informatica)|classi]] ([[ereditarietà (informatica)|ereditarietà]] fra classi, [[Firma (programmazione)|firme]] dei metodi, riferimenti a [[packageMetodo (Javaprogrammazione)|packagemetodi]], riferimenti a package solo per citarne alcuni) e agli inevitabili errori di battitura a cui si va incontro scrivendo documentazione. ''JavaDoc''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 [[Variabile (informatica)|parametri]] e delle variabili membro.
Con il progredire delle versioni ''JavaDoc''Javadoc diventò sempre più sofisticato e ricco di funzioni:
* inserimento di link[[Collegamento ipertestuale|collegamenti]], anche a JavaDocJavadoc esterni;
* inserimento dell'indicazione ''<code>@deprecated''</code> per segnalare classi e/o metodi destinati a scomparire in future versioni del software;
* opzioni per la formattazione avanzata;
* possibilità di creare le proprie ''Docletdoclet'': estensioni di JavaDocJavadoc che permettono di gestire a piacimento le varie fasi di generazione della documentazione
Le ''Docletdoclet'' 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]], [[LatexLaTeX]], 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 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 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 deidi 'commenti JavaDoc'Javadoc; questi sono racchiusi fra le sequenze di caratteri <code>/**</code> e <code>*/</code> (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:Javadoc.
* @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; ▼* @link: crea un collegamento ipertestuale alla documentazione locale o a risorse esterna (tipicamente internet) ▼
Lista dei [[Tag (metadato)|tag]] di Javadoc:
:{| class="wikitable"
[[de:Javadoc]]
! Tag !! Descrizione
[[en:Javadoc]]
|-
[[es:Javadoc]]
|<code>@author</code> || Nome dello sviluppatore.
[[fr:Javadoc]]
|-
[[ja:Javadoc]]
▲* |<code>@deprecated </code> :|| (vedere sopra) indica che l'elemento potrà essere eliminato da una versione successiva del software ;.
[[nl:Javadoc]]
|-
[[pt:Javadoc]]
|<code>@exception</code> || Indica eccezioni lanciate da un metodo; cf. <code>@throws</code>.
|-
▲* |<code>@link :</code> || creaCrea un collegamento ipertestuale alla documentazione locale o a risorse esterna (tipicamente internet) .
|-
|<code>@param</code> || Definisce i parametri di un metodo. Richiesto per ogni parametro.
|-
|<code>@return</code> || Indica i valori di ritorno di un metodo. Questo tag non va usato per metodi o costruttori che restituiscono {{Codice|codice=void|linguaggio=Java}}.
|-
|<code>@see</code> || Indica un'associazione a un altro metodo o classe.
|-
|<code>@since</code> || Indica quando un metodo è stato aggiunto a una classe.
|-
|<code>@throws</code> || Indica eccezioni lanciate da un metodo. Sinonimo di <code>@exception</code> introdotto in Javadoc 1.2.
|-
|<code>@version</code> || Indica il numero di versione di una classe o un metodo.
|}
Se si vuole il simbolo <code>@</code> senza l'intenzione di creare un tag di Javadoc, si può usare l'[[entità HTML]] {{Codice|codice=&#064;|linguaggio=HTML}} per evitare problemi in fase di ''[[parsing]]''.
== Collegamenti esterni ==
* {{Collegamenti esterni}}
* {{cita web|http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html|Guida su come scrivere commenti con Javadoc Tool|lingua=en}}
* {{cita web|1=http://myjavadoc.net|2=MyJavadoc.net (motore di ricerca)|lingua=en|accesso=10 settembre 2018|urlarchivio=https://web.archive.org/web/20170424184732/http://myjavadoc.net/|dataarchivio=24 aprile 2017|urlmorto=sì}}
{{Portale|informatica}}
▲[[Categoria: Piattaforma Java]]
| 