Java - Commenti sulla documentazione
Il linguaggio Java supporta tre tipi di commenti:
| Sr.No. | Commento e descrizione |
|---|---|
| 1 | /* text */ Il compilatore ignora tutto da / * a * /. |
| 2 | //text Il compilatore ignora tutto da // alla fine della riga. |
| 3 | /** documentation */ Questo è un commento alla documentazione e in generale è chiamato doc comment. IlJDK javadoclo strumento utilizza i commenti ai documenti quando prepara la documentazione generata automaticamente. |
Questo capitolo è tutto sulla spiegazione di Javadoc. Vedremo come utilizzare Javadoc per generare documentazione utile per il codice Java.
Cos'è Javadoc?
Javadoc è uno strumento fornito con JDK e viene utilizzato per generare la documentazione del codice Java in formato HTML dal codice sorgente Java, che richiede la documentazione in un formato predefinito.
Di seguito è riportato un semplice esempio in cui le righe all'interno di /*….*/ sono commenti Java su più righe. Allo stesso modo, la riga che precede // è un commento a riga singola Java.
Esempio
/**
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
*
* @author Zara Ali
* @version 1.0
* @since 2014-03-31
*/
public class HelloWorld {
public static void main(String[] args) {
// Prints Hello, World! on standard output.
System.out.println("Hello World!");
}
}È possibile includere tag HTML obbligatori all'interno della parte della descrizione. Ad esempio, il seguente esempio utilizza <h1> .... </h1> per l'intestazione e <p> è stato utilizzato per creare un'interruzione di paragrafo -
Esempio
/**
* <h1>Hello, World!</h1>
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
* <p>
* Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
*
* @author Zara Ali
* @version 1.0
* @since 2014-03-31
*/
public class HelloWorld {
public static void main(String[] args) {
// Prints Hello, World! on standard output.
System.out.println("Hello World!");
}
}I tag javadoc
Lo strumento javadoc riconosce i seguenti tag:
| Etichetta | Descrizione | Sintassi |
|---|---|---|
| @autore | Aggiunge l'autore di una classe. | @autore nome-testo |
| {@codice} | Visualizza il testo nel font del codice senza interpretarlo come markup HTML o tag javadoc nidificati. | {@code text} |
| {@docRoot} | Rappresenta il percorso relativo alla directory principale del documento generato da qualsiasi pagina generata. | {@docRoot} |
| @deprecato | Aggiunge un commento che indica che questa API non dovrebbe più essere utilizzata. | @deprecated deprecatedtext |
| @eccezione | Aggiunge un file Throws sottotitolo alla documentazione generata, con il nome della classe e il testo della descrizione. | @exception descrizione nome-classe |
| {@inheritDoc} | Eredita un commento da nearest classe ereditabile o interfaccia implementabile. | Eredita un commento dalla surperclasse immediata. |
| {@link} | Inserisce un collegamento in linea con l'etichetta di testo visibile che punta alla documentazione per il pacchetto, la classe o il nome membro di una classe a cui si fa riferimento. | {@link package.class # member label} |
| {@linkplain} | Identico a {@link}, tranne per il fatto che l'etichetta del link viene visualizzata in testo normale rispetto al carattere del codice. | {@linkplain package.class # member label} |
| @param | Aggiunge un parametro con il nome parametro specificato seguito dalla descrizione specificata nella sezione "Parametri". | @param descrizione nome parametro |
| @ritorno | Aggiunge una sezione "Resi" con il testo della descrizione. | @return descrizione |
| @vedere | Aggiunge un'intestazione "Vedere anche" con un collegamento o una voce di testo che punta a un riferimento. | @ vedi riferimento |
| @seriale | Utilizzato nel commento del documento per un campo serializzabile predefinito. | @serial campo-descrizione | includere | escludere |
| @serialData | Documenta i dati scritti dai metodi writeObject () o writeExternal (). | @serialData data-description |
| @serialField | Documenta un componente ObjectStreamField. | @serialField nome-campo tipo-campo descrizione-campo |
| @da | Aggiunge un'intestazione "Da" con il testo specificato dal momento alla documentazione generata. | @ dal rilascio |
| @throws | I tag @throws e @exception sono sinonimi. | @throws descrizione del nome della classe |
| {@valore} | Quando {@value} viene utilizzato nel commento del documento di un campo statico, visualizza il valore di quella costante. | {@value package.class # field} |
| @versione | Aggiunge un sottotitolo "Versione" con il testo della versione specificato ai documenti generati quando viene utilizzata l'opzione -version. | @version version-text |
Esempio
Il seguente programma utilizza alcuni dei tag importanti disponibili per i commenti sulla documentazione. Puoi utilizzare altri tag in base alle tue esigenze.
La documentazione sulla classe AddNum verrà prodotta nel file HTML AddNum.html ma allo stesso tempo verrà creato anche un file master con un nome index.html.
import java.io.*;
/**
* <h1>Add Two Numbers!</h1>
* The AddNum program implements an application that
* simply adds two given integer numbers and Prints
* the output on the screen.
* <p>
* <b>Note:</b> Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
* @author Zara Ali
* @version 1.0
* @since 2014-03-31
*/
public class AddNum {
/**
* This method is used to add two integers. This is
* a the simplest form of a class method, just to
* show the usage of various javadoc Tags.
* @param numA This is the first paramter to addNum method
* @param numB This is the second parameter to addNum method
* @return int This returns sum of numA and numB.
*/
public int addNum(int numA, int numB) {
return numA + numB;
}
/**
* This is the main method which makes use of addNum method.
* @param args Unused.
* @return Nothing.
* @exception IOException On input error.
* @see IOException
*/
public static void main(String args[]) throws IOException {
AddNum obj = new AddNum();
int sum = obj.addNum(10, 20);
System.out.println("Sum of 10 and 20 is :" + sum);
}
}Ora, elabora il file AddNum.java sopra utilizzando l'utilità javadoc come segue:
$ javadoc AddNum.java
Loading source file AddNum.java...
Constructing Javadoc information...
Standard Doclet version 1.7.0_51
Building tree for all the packages and classes...
Generating /AddNum.html...
AddNum.java:36: warning - @return tag cannot be used in method with void return type.
Generating /package-frame.html...
Generating /package-summary.html...
Generating /package-tree.html...
Generating /constant-values.html...
Building index for all the packages and classes...
Generating /overview-tree.html...
Generating /index-all.html...
Generating /deprecated-list.html...
Building index for all classes...
Generating /allclasses-frame.html...
Generating /allclasses-noframe.html...
Generating /index.html...
Generating /help-doc.html...
1 warning
$Puoi controllare tutta la documentazione generata qui - AddNum . Se stai usando JDK 1.7, javadoc non genera un ottimostylesheet.css, quindi suggeriamo di scaricare e utilizzare il foglio di stile standard da https://docs.oracle.com/javase/7/docs/api/stylesheet.css