Java-Dokumentationskommentare

Java unterstützt drei Kommentarstile:

  • Einzeilige Kommentare
  • Mehrzeilige Kommentare
  • Dokumentationskommentare

Die ersten beiden sind jeweils//und/* */, der dritte Typ heißt Dokumentationskommentare, der/**mit dem öffnenden Begrenzungszeichen beginnt und*/mit dem schließenden Begrenzungszeichen endet.

Für die ersten beiden Kommentartypen können Sie auf Folgendes verweisen:Java-Kommentare

Dokumentationskommentare ermöglichen es Ihnen, Informationen über Ihr Programm in das Programm einzubetten.

Sie können das javadoc-Tool verwenden, um die Informationen zu generieren und sie in eine HTML-Datei auszugeben.

Dokumentationskommentare machen es bequemer, Ihre Programminformationen aufzuzeichnen.

javadoc-Tags

Das javadoc-Tool erkennt die folgenden Tags:

Tag Beschreibung Beispiel
@author Identifiziert den Autor einer Klasse @author Beschreibung
@deprecated Kennzeichnet eine veraltete Klasse oder ein veraltetes Element @deprecated Beschreibung
{@docRoot} Gibt den Pfad zum aktuellen Dokumentstammverzeichnis an Verzeichnispfad
@exception Dokumentiert eine von einer Klasse geworfene Ausnahme @exception Ausnahmename Erklärung
{@inheritDoc} Erbt einen Kommentar von der direkt übergeordneten Klasse Erbt einen Kommentar von der unmittelbaren Oberklasse.
{@link} Fügt einen Link zu einem anderen Thema ein {@link name text}
{@linkplain} Fügt einen Link zu einem anderen Thema ein, aber der Link wird in einer Schriftart für reinen Text angezeigt Fügt einen Inline-Link zu einem anderen Thema ein.
@param Beschreibt einen Methodenparameter @param parameter-name Erklärung
@return Beschreibt den Typ des Rückgabewerts @return Erklärung
@see Gibt einen Link zu einem anderen Thema an @see Anker
@serial Beschreibt eine Serialisierungseigenschaft @serial Beschreibung
@serialData Beschreibt Daten, die durch die Methoden writeObject( ) und writeExternal( ) geschrieben werden @serialData Beschreibung
@serialField Beschreibt eine ObjectStreamField-Komponente @serialField Name Typ Beschreibung
@since Markiert, wann eine bestimmte Änderung eingeführt wird @since release
@throws Dasselbe wie das @exception-Tag. Das @throws-Tag hat dieselbe Bedeutung wie das @exception-Tag.
{@value} Zeigt den Wert einer Konstante an, die ein statisches Attribut sein muss. Zeigt den Wert einer Konstante an, die ein statisches Feld sein muss.
@version Gibt die Version einer Klasse an @version Info

Dokumentationskommentare

Nach der Eröffnung/**sind die erste Zeile oder die Zeilen die Hauptbeschreibung der Klasse, Variable oder Methode.

Danach können Sie einen oder mehrere verschiedene@Tags einfügen. Jedes@Tag muss am Anfang einer neuen Zeile stehen oder unmittelbar auf das Sternchen am Anfang einer Zeile folgen*。

Mehrere Tags desselben Typs sollten gruppiert werden. Wenn Sie beispielsweise drei@seeTags haben, können Sie sie nacheinander platzieren.

Unten sehen Sie ein Beispiel für einen Klassenkommentar:

/*** Diese Klasse zeichnet ein Balkendiagramm * @author example * @version 1.2 */

Was javadoc ausgibt

Das javadoc-Werkzeug nimmt den Quellcode Ihres Java-Programms als Eingabe und gibt HTML-Dateien aus, die die Kommentare Ihres Programms enthalten.

Die Informationen jeder Klasse befinden sich in einer separaten HTML-Datei. javadoc kann auch Vererbungsbaumstrukturen und Indizes ausgeben.

Da sich javadoc-Implementierungen unterscheiden, kann auch die Ausgabe unterschiedlich sein. Sie müssen Details wie die Version Ihres Java-Entwicklungssystems prüfen und die passende Javadoc-Version wählen.

Beispiel

Unten sehen Sie ein einfaches Beispiel für die Verwendung von Dokumentationskommentaren. Beachten Sie, dass jeder Kommentar vor dem Element steht, das er beschreibt.

Nach der Verarbeitung durch javadoc finden Sie den Kommentar der Klasse SquareNum in SquareNum.html.

Code der Datei SquareNum.java:

import java.io.*; /** * Diese Klasse demonstriert Dokumentationskommentare * @author Ayan Amhed * @version 1.2 */ public class SquareNum { /** * Diese Methode gibt das Quadrat von num zurück. * Dies ist eine mehrzeilige Beschreibung. Sie können * so viele Zeilen verwenden, wie Sie möchten. * @param num Der zu quadrierende Wert. * @return num zum Quadrat. */ public double square(double num) { return num * num; } /** * Diese Methode liest eine Zahl vom Benutzer ein. * @return Der als double eingegebene Wert. * @exception IOException Bei Eingabefehler. * @see IOException */ public double getNumber() throws IOException { InputStreamReader isr = new InputStreamReader(System.in); BufferedReader inData = new BufferedReader(isr); String str; str = inData.readLine(); return (new Double(str)).doubleValue(); } /** * Diese Methode demonstriert square(). * @param args Nicht verwendet. * @return Nichts. * @exception IOException Bei Eingabefehler. * @see IOException */ public static void main(String args[]) throws IOException { SquareNum ob = new SquareNum(); double val; System.out.println("Wert zum Quadrieren eingeben: "); val = ob.getNumber(); val = ob.square(val); System.out.println("Der quadrierte Wert ist " + val); } }

Wie unten gezeigt, verwenden Sie das javadoc-Tool, um die Datei SquareNum.java zu verarbeiten:

$ javadoc SquareNum.java
Loading source file SquareNum.java...
Constructing Javadoc information...
Standard Doclet version 1.5.0_13
Building tree for all the packages and classes...
Generating SquareNum.html...
SquareNum.java:39: 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...
Generating stylesheet.css...
1 warning
$
Andere Erweiterungen