what is javadoc how use it generate documentation
Questo tutorial spiega cosa sono lo strumento JavaDoc ei commenti e i metodi JavaDoc per generare la documentazione del codice:
JavaDoc è uno strumento speciale fornito con JDK. Viene utilizzato per generare la documentazione del codice del codice sorgente Java in formato HTML.
È un generatore di documentazione per il linguaggio Java di Sun Microsystems (attualmente Oracle Corporation).
=> Controlla TUTTI i tutorial Java qui.
Cosa imparerai:
Che cos'è JavaDoc
Questo strumento utilizza il formato 'commenti doc' per documentare le classi Java. IDE come Eclipse, IntelliJIDEA o NetBeans hanno uno strumento JavaDoc integrato per generare documentazione HTML. Abbiamo anche molti editor di file sul mercato che possono aiutare il programmatore a produrre sorgenti JavaDoc.
Oltre alla documentazione del codice sorgente, questo strumento fornisce anche API che creano 'doclet' e 'taglet' che utilizziamo per analizzare la struttura di un'applicazione Java.
Un punto da notare è che questo strumento non influisce in alcun modo sulle prestazioni dell'applicazione poiché il compilatore rimuove tutti i commenti durante la compilazione del programma Java.
Scrivere commenti nel programma e quindi utilizzare JavaDoc per generare la documentazione serve ad aiutare il programmatore / utente a comprendere il codice.
La documentazione HTML generata da JavaDoc è la documentazione API. Analizza le dichiarazioni e genera una serie di file sorgente. Il file di origine descrive campi, metodi, costruttori e classi.
Si noti che prima di utilizzare lo strumento JavaDoc sul nostro codice sorgente, è necessario includere commenti speciali JavaDoc nel programma.
Passiamo ora ai commenti.
Commenti JavaDoc
Il linguaggio Java supporta i seguenti tipi di commenti.
# 1) Commenti su una riga: Il commento su una sola riga è indicato da ' // 'E quando il compilatore li incontra, ignora tutto ciò che segue questi commenti fino alla fine della riga.
# 2) Commenti su più righe: I commenti su più righe sono rappresentati utilizzando ' /*….*/ '. Quindi, incontrando la sequenza '/ *', il compilatore ignora tutto ciò che segue questa sequenza finché non incontra la sequenza di chiusura '* /'.
# 3) Commenti sulla documentazione: Questi sono chiamati commenti Doc e vengono utilizzati dallo strumento per generare la documentazione API. I commenti al documento sono indicati come ' /** documentazione */ '. Come possiamo vedere, questi commenti sono diversi dai normali commenti descritti sopra. I commenti del documento possono anche contenere tag HTML al loro interno, come vedremo a breve.
domande dell'intervista all'help desk di livello 1
Quindi, per generare la documentazione API utilizzando questo strumento, dobbiamo fornire questi commenti alla documentazione (commenti alla documentazione) nel nostro programma.
Struttura di un commento JavaDoc
La struttura del commento del documento in Java è simile al commento su più righe tranne per il fatto che il commento del documento ha un asterisco in più (*) nel tag di apertura. Quindi il commento al documento inizia con '/ **' invece di '/ *'.
Inoltre, i commenti in stile JavaDoc possono contenere anche tag HTML.
Formato commenti JavaDoc
Sulla base del costrutto di programmazione su cui vogliamo documentare, possiamo inserire commenti al documento sopra qualsiasi costrutto come classe, metodo, campo, ecc. Passiamo attraverso esempi di ogni commento del documento del costrutto.
Formato a livello di classe
Il formato del commento al documento a livello di classe apparirà come mostrato di seguito:
/** * Mechanic * * Please see the {@link sth.javadoctutes.Person} class for true identity * @author SoftwareTestingHelp * */ public class Mechanic extends Person { // fields and methods } Come mostrato sopra, un commento al documento a livello di classe avrà tutti i dettagli incluso l'autore della classe, i collegamenti se presenti, ecc.
Formato a livello di metodo
Di seguito è riportato un esempio di un formato documento a livello di metodo.
/** * simple method description … * JavaDoc! *
* @param msg the message to be printed * @return void * @see JavaDoc * @since 2.0 */ public void printMessage (String msg) { // do things return 0; } Come possiamo vedere dall'esempio sopra, possiamo avere un numero qualsiasi di tag nel commento del documento del metodo. Possiamo anche avere paragrafi all'interno della descrizione del commento indicata da
...
.Abbiamo anche tag speciali per descrivere il valore restituito (@return) e i parametri del metodo (@param).
Formato a livello di campo
L'esempio seguente mostra il commento al documento per un campo.
/** * The public name of a message */ private String msg_txt;Come visto dall'esempio sopra, possiamo anche avere commenti semplici senza tag. Notare che JavaDoc non genera alcuna documentazione per i campi privati a meno che non specifichiamo un'opzione privata con il comando JavaDoc.
Ora parliamo dei tag utilizzati con i commenti del documento.
Tag JavaDoc
Java fornisce vari tag che possiamo includere nel commento del documento. Quando utilizziamo questi tag, lo strumento analizza questi tag per generare un'API ben formattata dal codice sorgente.
come aprire un file mkv
Ogni tag fa distinzione tra maiuscole e minuscole e inizia con un segno '@'. Ogni tag inizia all'inizio della riga come possiamo vedere dagli esempi precedenti. Altrimenti, il compilatore lo tratta come un normale testo. Per convenzione, gli stessi tag vengono inseriti insieme.
Esistono due tipi di tag che possiamo utilizzare nel commento del documento.
# 1) Tag di blocco : I tag di blocco hanno la forma di @ tag_name .
I tag di blocco possono essere inseriti nella sezione dei tag e seguire la descrizione principale .
# 2) Tag in linea :I tag inline sono racchiusi tra parentesi graffe e hanno la forma, {@tag_name} . I tag inline possono essere posizionati ovunque all'interno del commento del documento.
La tabella seguente elenca tutti i tag che possono essere utilizzati nei commenti del documento.
| Etichetta | Descrizione | Si applica a |
|---|---|---|
| @return descrizione | Fornisce la descrizione del valore restituito. | Metodo |
| @autore xyz | Indica l'autore della classe, dell'interfaccia o dell'enumerazione. | Classe, interfaccia, enumerazione |
| {@docRoot} | Questo tag ha il percorso relativo alla directory principale del documento. | Classe, interfaccia, enumerazione, campo, metodo |
| @version version | Specifica l'immissione della versione del software. | Classe, interfaccia, enumerazione |
| @since dal testo | Specifica da quando esiste questa funzionalità | Classe, interfaccia, enumerazione, campo, metodo |
| @ vedi riferimento | Specifica riferimenti (collegamenti) ad altra documentazione | Classe, interfaccia, enumerazione, campo, metodo |
| @param name description | Utilizzato per descrivere il parametro / argomento del metodo. | Metodo |
| @exception classname descrizione | Specifica l'eccezione che il metodo può generare nel suo codice. | Metodo |
| @throws classname descrizione | ||
| @ descrizione deprecata | Specifica se il metodo è obsoleto | Classe, interfaccia, enumerazione, campo, metodo |
| {@inheritDoc} | Utilizzato per copiare la descrizione dal metodo sovrascritto in caso di ereditarietà | Metodo di sostituzione |
| {@link reference} | Fornisce riferimenti o collegamenti ad altri simboli. | Classe, interfaccia, enumerazione, campo, metodo |
| {@linkplain reference} | Uguale a {@link} ma viene visualizzato in testo normale. | Classe, interfaccia, enumerazione, campo, metodo |
| {@value #STATIC_FIELD} | Descrivi il valore di un campo statico. | Campo statico |
| {@code literal} | Utilizzato per formattare il testo letterale nel carattere del codice simile a {@literal}. | Class, Interface, Enum, Field, Method |
| {@literal literal} | Indicates literal text. the enclosed text is interpreted literally without any style formatting. | Class, Interface, Enum, Field, Method |
| {@serial literal} | Description of a serializable field. | Field |
| {@serialData literal} | Documents the data written by the writeExternal( ) or writeObject( ) methods. | Field, Method |
| {@serialField literal} | Describes an ObjectStreamField component. | Field |
Generate Java Doc
To create a JavaDoc you do not need to compile the Java file. We can generate JavaDoc documentation in two ways.
#1) Using JavaDoc Command Via Command Line
The command-line tool allows us to run the command through it.
This command can be executed on a command line and has the following syntax.
user@sth:~$javadoc –d doc src*
In the above command, we assume that all the files and Java classes are in the src folder. Also, the documentation will be generated in the specified ‘doc’ directory.
Note that running the “javadoc” command without any parameters or flags results in an error.
#2) Using The Tool From Any Of The Java IDEs.
All the major Java IDEs provide built-in functionality of generating documentation using the JavaDoc tool.
Using this built-in functionality is easier and also recommended than using a command-line tool to generate Java documentation.
Using JavaDoc With IntelliJIdea
Let’s generate documentation for a simple program using IntelliJIdea IDE.
We will consider the following program for which we have provided doc comments.
/** * Main class * * Please see the {@link www.softwaretestinghelp.com} class for true identity * @author SoftwareTestingHelp * */ public class Main{ /** * main method description … * JavaDoc! *
* @param args() string array * @return void * @see JavaDoc * */ public static void main(String args()) { System.out.println('Hello,World!!'); } } Sappiamo che non è necessario compilare il programma o il progetto per generare JavaDoc. IntelliJIdea Ide fornisce uno strumento integrato per generare la documentazione. Seguire i passaggi seguenti per generare la documentazione utilizzando IntelliJIdea.
- Fare clic su Strumenti -> Genera JavaDoc
- La schermata seguente viene visualizzata quando si fa clic sullo strumento JavaDoc.
Qui possiamo specificare se vogliamo generare la documentazione per l'intero progetto o solo una classe ecc. Possiamo anche specificare la directory di output dove verranno generati i file di documentazione. Ci sono varie altre specifiche come mostrato nella figura sopra.
Fare clic su OK una volta specificati tutti i parametri.
- Ora possiamo vedere il processo di generazione di Java Doc nella finestra di output. Una finestra di output di Java Doc di esempio appare come mostrato di seguito:
- Al termine della generazione, vengono generati i seguenti file.
- Come abbiamo specificato la classe Main, viene generato il file Main.html. Notare che index.html ha anche gli stessi contenuti di Main.html.
- Il file help-doc.html contiene le definizioni generali delle entità Java. Di seguito viene mostrato un esempio dei contenuti di questo file.
- Allo stesso modo, di seguito è riportato un contenuto di esempio nel file Main.html
Quindi, questo è il modo in cui possiamo generare la documentazione usando questo strumento nell'idea di IntelliJ. Possiamo seguire passaggi simili in altri IDE Java come Eclipse e / o NetBeans.
Domande frequenti
Q # 1) Qual è l'uso di JavaDoc?
Risposta: Lo strumento JavaDoc viene fornito con JDK. Viene utilizzato per generare la documentazione del codice per il codice sorgente Java in formato HTML. Questo strumento richiede che i commenti nel codice sorgente siano forniti in un formato predefinito come /**….*/. Questi sono anche chiamati commenti ai documenti.
D # 2) Qual è l'esempio di documentazione Java?
Risposta: Lo strumento di documentazione Java Doc genera file HTML in modo che possiamo visualizzare la documentazione dal browser web. Il vero esempio dal vivo della documentazione JavaDoc è la documentazione per le librerie Java su Oracle Corporation, http://download.oracle.com/javase/6/ documenti /fuoco/.
D # 3) I metodi privati richiedono JavaDoc?
Risposta: No. I campi e i metodi privati sono riservati agli sviluppatori. Non c'è logica nel fornire documentazione per metodi o campi privati che non sono accessibili all'utente finale. Java Doc inoltre non genera documentazione per soggetti privati.
miglior software desktop remoto per Windows
D # 4) Cos'è il comando JavaDoc?
Risposta: Questo comando analizza le dichiarazioni e i commenti ai documenti nei file di origine Java e genera le pagine di documentazione HTML corrispondenti contenenti la documentazione per classi pubbliche e protette, classi nidificate, costruttori, metodi, campi e interfacce.
Tuttavia, JavaDoc non genera documentazione per entità private e classi interne anonime.
Conclusione
Questo tutorial ha descritto lo strumento JavaDoc fornito con JDK utile per generare la documentazione del codice per il codice sorgente Java in formato HTML. Possiamo generare la documentazione eseguendo il comando Java Doc tramite lo strumento di comando o utilizzando la funzionalità JavaDoc incorporata disponibile nella maggior parte degli IDE Java.
Abbiamo visto come possiamo usare lo strumento con IntelliJIdea Java IDE per generare la documentazione. Il tutorial ha anche spiegato vari tag che possono essere usati con i commenti ai documenti in modo che lo strumento possa generare una documentazione user-friendly che dettaglia tutte le informazioni relative al codice sorgente.
=> Visita qui per imparare Java da zero.
Lettura consigliata
- Nozioni di base su Java: sintassi Java, classe Java e concetti principali di Java
- Distribuzione Java: creazione ed esecuzione di file JAR Java
- Java Virtual Machine: come JVM aiuta nell'esecuzione di applicazioni Java
- Tutorial JAVA per principianti: oltre 100 tutorial video Java pratici
- Java Integer e Java BigInteger Class con esempi
- Componenti Java: piattaforma Java, JDK, JRE e Java Virtual Machine
- Come creare la documentazione API in Postman?