Java - Dokumentationskommentare
Die Java-Sprache unterstützt drei Arten von Kommentaren:
| Sr.Nr. | Kommentar & Beschreibung |
|---|---|
| 1 | /* text */ Der Compiler ignoriert alles von / * bis * /. |
| 2 | //text Der Compiler ignoriert alles von // bis zum Ende der Zeile. |
| 3 | /** documentation */ Dies ist ein Dokumentationskommentar und wird im Allgemeinen aufgerufen doc comment. DasJDK javadocDas Tool verwendet Dokumentkommentare, wenn automatisch generierte Dokumentationen erstellt werden. |
In diesem Kapitel geht es darum, Javadoc zu erklären. Wir werden sehen, wie wir Javadoc verwenden können, um nützliche Dokumentation für Java-Code zu generieren.
Was ist Javadoc?
Javadoc ist ein Tool, das mit JDK geliefert wird und zum Generieren von Java-Codedokumentation im HTML-Format aus Java-Quellcode verwendet wird, für die Dokumentation in einem vordefinierten Format erforderlich ist.
Es folgt ein einfaches Beispiel, in dem die Zeilen in /*….*/ mehrzeilige Java-Kommentare sind. In ähnlicher Weise ist die Zeile, die // vorausgeht, ein einzeiliger Java-Kommentar.
Beispiel
/**
* 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!");
}
}Sie können die erforderlichen HTML-Tags in den Beschreibungsteil aufnehmen. Im folgenden Beispiel wird beispielsweise <h1> .... </ h1> als Überschrift verwendet, und <p> wurde zum Erstellen von Absatzumbrüchen verwendet.
Beispiel
/**
* <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!");
}
}Die Javadoc-Tags
Das Javadoc-Tool erkennt die folgenden Tags:
| Etikett | Beschreibung | Syntax |
|---|---|---|
| @Autor | Fügt den Autor einer Klasse hinzu. | @author name-text |
| {@Code} | Zeigt Text in Codeschrift an, ohne den Text als HTML-Markup oder verschachtelte Javadoc-Tags zu interpretieren. | {@code text} |
| {@docRoot} | Stellt den relativen Pfad zum Stammverzeichnis des generierten Dokuments von einer generierten Seite dar. | {@docRoot} |
| @deprecated | Fügt einen Kommentar hinzu, der angibt, dass diese API nicht mehr verwendet werden soll. | @deprecated veralteter Text |
| @Ausnahme | Fügt a hinzu Throws Unterüberschrift der generierten Dokumentation mit dem Klassennamen und dem Beschreibungstext. | @exception Klassenname Beschreibung |
| {@inheritDoc} | Erbt einen Kommentar von der nearest vererbbare Klasse oder implementierbare Schnittstelle. | Erbt einen Kommentar aus der unmittelbaren Oberklasse. |
| {@Verknüpfung} | Fügt einen Inline-Link mit der sichtbaren Textbezeichnung ein, der auf die Dokumentation für das angegebene Paket, die Klasse oder den Mitgliedsnamen einer referenzierten Klasse verweist. | {@link package.class # member label} |
| {@linkplain} | Identisch mit {@link}, außer dass die Beschriftung des Links im Klartext als Code-Schriftart angezeigt wird. | {@linkplain package.class # member label} |
| @param | Fügt dem Abschnitt "Parameter" einen Parameter mit dem angegebenen Parameternamen gefolgt von der angegebenen Beschreibung hinzu. | @param Parametername Beschreibung |
| @Rückkehr | Fügt einen Abschnitt "Rückgabe" mit dem Beschreibungstext hinzu. | @ Rückgabe Beschreibung |
| @sehen | Fügt eine Überschrift "Siehe auch" mit einem Link oder Texteintrag hinzu, der auf eine Referenz verweist. | @ Siehe Referenz |
| @serial | Wird im Dokumentkommentar für ein standardmäßiges serialisierbares Feld verwendet. | @serielle Feldbeschreibung | include | ausschließen |
| @serialData | Dokumentiert die Daten, die mit den Methoden writeObject () oder writeExternal () geschrieben wurden. | @serialData Datenbeschreibung |
| @serialField | Dokumentiert eine ObjectStreamField-Komponente. | @serialField Feldname Feldtyp Feldbeschreibung |
| @schon seit | Fügt der generierten Dokumentation eine Überschrift "Seit" mit dem angegebenen Seit-Text hinzu. | @ seit Veröffentlichung |
| @ wirft | Die Tags @throws und @exception sind Synonyme. | @throws Klassenname Beschreibung |
| {@Wert} | Wenn {@value} im Dokumentkommentar eines statischen Felds verwendet wird, wird der Wert dieser Konstante angezeigt. | {@value package.class # field} |
| @Ausführung | Fügt den generierten Dokumenten eine Unterüberschrift "Version" mit dem angegebenen Versionstext hinzu, wenn die Option -version verwendet wird. | @version version-text |
Beispiel
Das folgende Programm verwendet einige der wichtigen Tags, die für Dokumentationskommentare verfügbar sind. Sie können je nach Ihren Anforderungen andere Tags verwenden.
Die Dokumentation zur AddNum-Klasse wird in der HTML-Datei AddNum.html erstellt, gleichzeitig wird jedoch auch eine Master-Datei mit dem Namen index.html erstellt.
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);
}
}Verarbeiten Sie nun die obige Datei AddNum.java mit dem Dienstprogramm javadoc wie folgt:
$ 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
$Sie können die gesamte generierte Dokumentation hier überprüfen - AddNum . Wenn Sie JDK 1.7 verwenden, generiert javadoc kein großartiges Ergebnisstylesheet.cssWir empfehlen daher, das Standard-Stylesheet von herunterzuladen und zu verwenden https://docs.oracle.com/javase/7/docs/api/stylesheet.css