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