Javadoc: differenze tra le versioni

Versione delle 19:02, 9 dic 2005

Versione attuale delle 22:34, 22 nov 2024

(41 versioni intermedie di 30 utenti non mostrate)

Riga 1:

'''JavaDocJavadoc''' è un [[toolapplicazione (informatica)|applicativo]] incluso nel kit di sviluppo [[Java (linguaggio)|JavaDevelopment Kit]] della [[Sun Microsystems]], utilizzato per la generazione automatica della [[Documentazione del software|documentazione]] del [[Codice_Codice (informatica)|codice sorgente]] scritto in [[Java (linguaggio di programmazione)|linguaggio Java]].

{{da aiutare mese|novembre 2005}}

'''JavaDoc''' è un [[tool]] incluso nel kit di sviluppo [[Java (linguaggio)|Java]] della Sun, utilizzato per la generazione automatica della documentazione del [[Codice_(informatica)|codice sorgente]].

== Storia ==

Javadoc nacque come toolstrumento interno utilizzato dai ricercatori della [[Sun Microsystems|Sun]] che stavano lavoravanolavorando 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 un 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 [[Metodo (programmazione)|metodi]], riferimenti a partirepackage dasolo specialiper 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 utilizzati(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 nelvariabili codicemembro.

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

Con il progredire delle versioni ''Javadoc'' è diventato sempre più sofisticato e ricco di funzioni, aggiungendo la possibilità di creare le proprie ''Doclet''. Le ''Doclet'' altro non sono che estensioni di Javadoc che permettono di gestire a piacimento le varie fasi di generazione della documentazione; questa grande flessibilità permise di creare tool in grado di generare schemi [[UML]], documentazione in [[PDF]] e analizzatori di dipendenze.

* inserimento di [[Collegamento ipertestuale|collegamenti]], anche a Javadoc 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 ''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:

Il grande successo di Javadoc è dovuto in gran parte alla possibilità di poter creare con facilità una documentazione dall'aspetto professionale, del tutto simile a quella ufficiale. 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.

* 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 in gran parte 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, cioè la gestione dei documenti relativi ai propri programmi. I [[file]] [[html]]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 di commenti 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.

Il [[tool]] '''Javadoc''' genera la [[documentazione]] estraendo informazioni direttamente dal [[Codice_(informatica)|codice]] opportunamente commentato.

Lista dei [[Tag (metadato)|tag]] di Javadoc:

:{| class="wikitable"

! Tag !! Descrizione

|-

|<code>@author</code> || Nome dello sviluppatore.

|-

|<code>@deprecated</code> || (vedere sopra) indica che l'elemento potrà essere eliminato da una versione successiva del software.

|-

|<code>@exception</code> || Indica eccezioni lanciate da un metodo; cf. <code>@throws</code>.

|-

|<code>@link</code> || Crea 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=&amp;#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]]

'''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.

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.