Java - Dokumentationskommentare
Die Java-Sprache unterstützt drei Arten von Kommentaren −
| Sr.No. | Kommentar &Beschreibung |
|---|---|
| 1 | /* Text */ Der Compiler ignoriert alles von /* bis */. |
| 2 | //Text Der Compiler ignoriert alles von // bis zum Zeilenende. |
| 3 | /** Dokumentation */ Dies ist ein Dokumentationskommentar und wird im Allgemeinen als Dokumentenkommentar bezeichnet . Das JDK-Javadoc Tool verwendet Doc-Kommentare bei der Erstellung automatisch generierter Dokumentation. |
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-Code-Dokumentation im HTML-Format aus Java-Quellcode verwendet wird, der eine Dokumentation in einem vordefinierten Format erfordert.
Es folgt ein einfaches Beispiel, bei dem die Zeilen in /*….*/ mehrzeilige Java-Kommentare sind. Ebenso ist die vorangestellte Zeile // 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 erforderliche HTML-Tags in den Beschreibungsteil einfügen. Zum Beispiel verwendet das folgende Beispiel
....
für die Überschrift undwurde verwendet, um einen Absatzumbruch zu erstellen −
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 −
| Tag | Beschreibung | Syntax |
|---|---|---|
| @Autor | Fügt den Autor einer Klasse hinzu. | @Autorenname-Text |
| {@code} | Zeigt Text in Code-Schriftart an, ohne den Text als HTML-Markup oder verschachtelte Javadoc-Tags zu interpretieren. | {@Codetext} |
| {@docRoot} | Repräsentiert den relativen Pfad zum Stammverzeichnis des generierten Dokuments von jeder generierten Seite. | {@docRoot} |
| @veraltet | Fügt einen Kommentar hinzu, der angibt, dass diese API nicht mehr verwendet werden sollte. | @deprecated veralteter Text |
| @Exception | Fügt einen Wurf hinzu Unterüberschrift zur generierten Dokumentation, mit Klassenname und Beschreibungstext. | @exception class-name description |
| {@inheritDoc} | Übernimmt einen Kommentar vom nächsten vererbbare Klasse oder implementierbare Schnittstelle. | Erbt einen Kommentar von der unmittelbaren Superklasse. |
| {@link} | Fügt einen Inline-Link mit dem sichtbaren Textlabel 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 Bezeichnung des Links im Klartext als Code-Schriftart angezeigt wird. | {@linkplain package.class#member label} |
| @param | Fügt einen Parameter mit dem angegebenen Parameternamen gefolgt von der angegebenen Beschreibung zum Abschnitt "Parameter" hinzu. | @param parameter-name description |
| @return | Fügt einen Abschnitt "Retouren" mit dem Beschreibungstext hinzu. | @return description |
| @see | Fügt eine „Siehe auch“-Überschrift mit einem Link oder Texteintrag hinzu, der auf eine Referenz verweist. | @siehe Referenz |
| @serial | Wird im Dokumentkommentar für ein standardmäßig serialisierbares Feld verwendet. | @serial Feldbeschreibung | beinhalten | ausschließen |
| @serialData | Dokumentiert die Daten, die von den Methoden writeObject( ) oder writeExternal( ) geschrieben wurden. | @serialData Datenbeschreibung |
| @serialField | Dokumentiert eine ObjectStreamField-Komponente. | @serialField Feldname Feldtyp Feldbeschreibung |
| @since | Fügt der generierten Dokumentation eine „Seit“-Überschrift mit dem angegebenen Seit-Text hinzu. | @seit Veröffentlichung |
| @throws | Die Tags @throws und @exception sind Synonyme. | @throws Beschreibung des Klassennamens |
| {@value} | Wenn {@value} im Dokumentkommentar eines statischen Felds verwendet wird, zeigt es den Wert dieser Konstante an. | {@value package.class#field} |
| @version | Fügt eine „Version“-Unterüberschrift mit dem angegebenen Versionstext zu den generierten Dokumenten 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 über die AddNum-Klasse wird in der HTML-Datei AddNum.html erstellt, aber gleichzeitig wird 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 AddNum.java-Datei mit dem javadoc-Dienstprogramm 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 keine großartige stylesheet.css , daher empfehlen wir, das Standard-Stylesheet von https://docs.oracle.com/javase/7/docs/api/stylesheet.css
herunterzuladen und zu verwendenJava