Share
Questa breve lezione copre Javadoc, uno strumento utile per generare documentazione dai tuoi file sorgente Java. Questa lezione fa parte di una serie continua di tutorial per gli sviluppatori che stanno imparando Java per sviluppare applicazioni Android.
Javadoc è un'utilità fornita con Java SDK che consente agli sviluppatori di generare documentazione del codice dai file di origine Java. Gli ambienti di sviluppo come Eclipse hanno il supporto integrato per Javadoc e possono generare materiali di riferimento HTML ricercabili dai commenti in stile Javadoc. In effetti, il riferimento all'SDK di Android è una forma di documentazione Javadoc.
La documentazione Javadoc utilizza una combinazione di elaborazione del codice sorgente (e controllo di tipi, parametri, ecc.) E lettura di tag di commento speciali che lo sviluppatore fornisce come metadati associati a una sezione di codice.
Un commento in stile Javadoc deve comparire prima del codice a cui è associato. Ad esempio, un commento Javadoc per una classe dovrebbe essere appena sopra la dichiarazione della classe e un commento per un metodo dovrebbe essere appena sopra la dichiarazione del metodo. Ogni commento dovrebbe iniziare con una breve descrizione, seguita da un'opzione più lunga. Quindi puoi includere un numero di tag di metadati diversi, che devono essere forniti in un ordine specifico. Alcuni tag importanti includono:
Puoi anche creare i tuoi tag personalizzati da utilizzare nella documentazione.
Mentre scrivi il codice in Eclipse, puoi generare un commento in stile Javadoc selezionando l'elemento che desideri commentare (nome di una classe, nome del metodo, ecc.) E premendo Alt-Maiusc-J (Cmd-Maiusc-J su Mac). Questo creerà un commento di base in stile Javadoc per permetterti di inserire i dettagli.
Diamo un'occhiata a un esempio. Ecco un semplice commento Javadoc che descrive una classe:
/ ** * Attività per il caricamento delle risorse di layout * * Questa attività viene utilizzata per visualizzare diverse risorse di layout per un'esercitazione sulla progettazione dell'interfaccia utente. * * @author LED * @version 2010.1105 * @since 1.0 * / public class LayoutActivity estende l'attività
Ecco come apparirà quando generi la documentazione Javadoc:
Diamo un'occhiata a un esempio. Ecco un semplice commento Javadoc che descrive un campo all'interno di una classe:
/ ** * Tag di debug per utilizzare l'output di debug di registrazione su LogCat * / stringa finale statica privata DEBUG_TAG = "MyActivityDebugTag";
Ecco come apparirà quando generi la documentazione Javadoc:
Ora diamo un'occhiata a due esempi di commenti sui metodi. Ecco un semplice commento Javadoc che descrive un metodo all'interno di una classe:
/ ** * Metodo che aggiunge due interi insieme * * @param a Il primo numero intero da aggiungere * @param b Il secondo intero da aggiungere * @return La somma risultante di a e b * / public int addIntegers (int a, int b ) return (a + b);
Ora diamo un'occhiata a un metodo che restituisce void, ma genera un'eccezione:
/ ** * Questo metodo genera semplicemente un'eccezione se il parametro in entrata a non è un numero positivo, solo per divertimento. * * @param a Se lanciare o meno un'eccezione * @throws Exception * / public void throwException (boolean shouldThrow) genera Exception if (shouldThrow == true) throw new Exception ();
Ecco come apparirà quando generi la documentazione Javadoc per questi due metodi:
Per generare la documentazione del codice Javadoc in Eclipse, vai al menu Progetto e scegli l'opzione "Genera Javadoc ...". Verrà avviato un wizard che consente di scegliere i progetti per generare la documentazione.
Da questa procedura guidata, dovresti puntare Eclipse sullo strumento della riga di comando javadoc.exe appropriato (lo troverai nella directory / bin di JDK). È inoltre possibile configurare alcune impostazioni della documentazione, come se si desidera documentare tutto il codice o solo le classi visibili, i membri, ecc. Infine, scegliere una destinazione per i file della documentazione.
Anche senza generare i file Javadoc, Eclipse mostrerà la documentazione in stile Javadoc quando passi il mouse sopra i tuoi metodi e simili, come mostrato nella figura seguente.
Puoi trovare ulteriori informazioni dal riferimento Javadoc sul sito Web di Oracle. Sono disponibili anche utili FAQ Javadoc.
In questa rapida lezione hai imparato a conoscere Javadoc, un potente strumento utilizzato dagli sviluppatori Java per documentare accuratamente il codice sorgente per scopi di riferimento e di manutenzione. Eclipse, l'ambiente di sviluppo utilizzato da molti sviluppatori Android, ha il supporto integrato per Javadoc.
Gli sviluppatori mobili Lauren Darcey e Shane Conder hanno coautore diversi libri sullo sviluppo di Android: un libro di programmazione approfondito intitolato Sviluppo di applicazioni wireless Android e Sams TeachYourself Sviluppo di applicazioni Android in 24 ore. Quando non scrivono, passano il loro tempo a sviluppare software mobile presso la loro azienda ea fornire servizi di consulenza. Possono essere contattati via email a [email protected], tramite il loro blog su androidbook.blogspot.com e su Twitter @androidwireless.
Accentsconagua