Dokumentationskommentare in Java

Direkt vor die Deklaration einer Methode kann ein Kommentar geschrieben werden, der die Schnittstelle der Methode beschreibt. Wenn der Kommentar mit dem Zeichentripel "/**" eingeleitet wird, dann wird damit gekennzeichnet, daß er zur automatischen Herstellung von Dokumentationsdateien verwendet werden soll.

Solch ein Kommentar wird auch als Dokumentationskommentar (documentation comment , doc comment ) bezeichnet. Alle anderen Kommentare kann man auch als Implementationskommentare (implementation comments ) ansehen, da sie sich mit Aspekten der Implementation beschäftigen sollten.

Normalerweise wird ein Dokumentationskommentar direkt vor das zu Dokumentierende geschrieben. So finden sich in dem Beispielprogramm "Kuckuck3d.java" Dokumentationskommentare vor jeder Methodendeklaration.

Kuckuck3d.java

public final class Kuckuck3d { 
  /** Den Refrain des Liedes "Auf einem Baum ein Kuckuck sass" ausgeben. */ 
  public static void refrainAusgeben() 
  { java.lang.System.out.println( "Sim sa la dim, bam ba," ); 
    java.lang.System.out.println( "Sa la du, sa la dim -" ); }
  /** Das Lied "Auf einem Baum ein Kuckuck sass" ausgeben. */ 
  public static void main( final java.lang.String[] args ) 
  { /* Kann man das nicht noch verkuerzen? */ 
    { java.lang.System.out.println( "Auf einem Baum ein Kuckuck, -" ); 
      refrainAusgeben(); 
      java.lang.System.out.println( "Auf einem Baum ein Kuckuck sass." ); } 
    { java.lang.System.out.println( "Da kam ein junger Jaeger, -" ); 
      refrainAusgeben(); 
      java.lang.System.out.println( "Da kam ein junger Jaegersmann." ); } 
    { java.lang.System.out.println( "Der schoss den armen Kuckuck, -" ); 
      refrainAusgeben(); 
      java.lang.System.out.println( "Der schoss den armen Kuckuck tot." ); }}}

Zum Java -Entwicklungssystem gehört ein Werkzeug "javadoc", das es erlaubt, Dokumentationsdateien automatisch aus einer wie beschrieben mit Dokumentationskommentaren angereicherten Quelldatei zu erzeugen. Dieses Werkzeug bietet noch mehr Möglichkeiten als hier beschrieben—In dieser Lektion wird nur ein einfaches Beispiel der Verwendung vorgestellt.

Konsole [Ausschnitt]

javadoc Kuckuck3d.java
Loading source file Kuckuck3d.java... 
Constructing Javadoc information... 
Standard Doclet version 1.4.0

Das Werkzeug "javadoc" erzeugt dann unter anderem eine HTML -Datei "Kuckuck3d.html" mit der gewünschten Dokumentation.

Kuckuck3d [Dokumentation, Ausschnitt]

Method Summary 
  static void main( java.lang.String[] args ) 
    Das Lied "Auf einem Baum ein Kuckuck sass" ausgeben. 
  static void refrainAusgeben() 
    Den Refrain des Liedes "Auf einem Baum ein Kuckuck sass" ausgeben.

Auch der Kommentar "/* Kann man das nicht noch verkuerzen? */" wird nicht in die Dokumentation aufgenommen, weil er nicht als Dokumentationskommentar gekennzeichnet ist.

Das Zeichentripel "///" kann nicht verwendet werden, um einen einzeiligen Dokumentationskommentar einzuleiten.

Mit der Option "encoding" und der Option "docencoding" wird die Codierung des Quelltextes bzw. der zu erzeugenden Dokumentation festlegt. Die möglichen Werte sind wie bei der Option "encoding" von des Kommandos "javac". Eine Angabe dieser Optionen kann nötig werden, wenn die Quelldateien nicht in der Codierung "US-ASCII" vorliegen.

Aufruf mit Angabe von Codierungen [Ausschnitt]

javadoc -encoding UTF-8 -docencoding UTF-8 Kuckuck3d.java

Dokumentation

Mit der ersten mit "@" anfangenden Zeile eines Dokumentationskommentars wird die allgemeine Beschreibung der Methode "wochentage" beendet. Die Markierung "@return" kennzeichnet dann die Beschreibung des Wertes einer Anwendung einer Wertmethode.

Dokumentation [Ausschnitt]

wochentage 
  int wochentage() 
  Ergibt Zahl der Wochentage.  
  Returns: 
    Zahl der Wochentage

Main.java

public final class Main 
{ /** 
   * Ergibt Zahl der Wochentage. 
   * @return Zahl der Wochentage 
   */ 
  public static int wochentage(){ return 7; }
  /** 
   * Ausgabe der Anzahl der Tage in zwei Wochen. 
   */ 
  public static void main( final java.lang.String[] args ) 
  { java.lang.System.out.println( 2 * wochentage() ); }}

Parameterdokumentation

Account.java

final class Account
{ private double balance;
  /** Initialize the account. */
  public Account(){ balance = 0.; }
  /** Converts a string representation of a number
    to a double value. 
    @param text      the string to be converted
    @return          the double value of the text */
  private static double val( final String text )
  { return new Double( text ).doubleValue(); }
  /** Represents a double value by a string. 
    @param number    the number to be represented.
    @return          the string representing the number */
  private static String str( final double number )
  { return new Double( number ).toString(); }
  /** Deposit money into an account.
    @param amount the money to be deposited into the account
    @return       the money accepted and added to the balance */
  public String deposit( final String amount )
  { double amountValue = val( amount );
    balance += amountValue; return str( amountValue ); }
  /** Retrieve the balance of the account.
    @return          the current balance of the account */
  public String balance(){ return str( balance ); }}

AccountClient.java

public final class AccountClient
{ public static void main( final java.lang.String[] args )
  { final Account a = new Account();
    java.lang.System.out.println( a.deposit( "0.1" ) ); 
    java.lang.System.out.println( a.balance() ); 
    java.lang.System.out.println( a.deposit( "0.1" ) ); 
    java.lang.System.out.println( a.balance() ); 
    java.lang.System.out.println( a.deposit( "0.1" ) ); 
    java.lang.System.out.println( a.balance() ); }}

System.out

0.1
0.1
0.1
0.2
0.1
0.30000000000000004

Dokumentation eines Konstruktors mit Parametern

PersonName.java

/** The name of a person (last name and first name) */
class PersonName  
{ final private String last;  
  final private String first;
  /** Initialize the person name. 
   * @param last  the last name  
   * @param first the last name */
  PersonName( final String last, final String first ) 
  { this.last = last; this.first = first; }
  /** compare the Name to an object.  
   * @return 0 */
  int compareTo( final Object other ) 
  { return 0; }}

Dokumentation

Um ein Paket zu dokumentieren sollte eine Datei "package.html" im Verzeichnis des Paketes erstellt werden. Dabei wird das Paket vor der "h2"-Überschrift "Package Specification" kurz charakterisiert und kann nach dieser Überschrift ausführlicher beschrieben werden. Diese Angaben werden dann in die erstellte Dokumentation mit einbezogen. Ohne Kenntnisse in der Sprache HTML kann die hier angegebene Datei "package.html" als Vorlage verwendet werden, in der die beiden deutschsprachigen Absätze durch einen eigenen Text ersetzt werden. Dabei sollten aber Sonderzeichen (wie Umlaute oder das Kleiner-Zeichen) vermieden werden oder zumindest die Regeln zum Schreiben von Sonderzeichen mit HTML erlernt werden.

package.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" 
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html><head><title>komm</title></head><body>
Unterstuetzung fuer Kommunikation.
<h2>Package Specification</h2>
Dieses Paket enthaelt Klassen fuer die Kommunikation 
mit Menschen, wie beispielsweise eine Klasse zur 
Begruessung von Menschen.
</body></html>

Die öffentliche Schnittstelle

Das Wort „Schnittstelle“ hat zwei Bedeutungen: Zum einen bezeichnet es das, was in Java mit dem Schlüsselworte »interface« deklariert wird. Zum anderen meint man damit, all das, was man von „außen“ von einer Klasse (einem Objekt, einem Feld oder einer Methode) sehen kann. Dies ist bei einer Methode im wesentlichen die „abstrakte Methode“, also die Beschreibung der Methode von den Schlüsselwörtern ganz am Anfang ihrer Deklaration bis hin zur Angabe ihres Deskriptors (also der Rückgabespezifikation und der Signatur), jedoch ohne die Implementation der Methode, also den Hauptblock der Methode (das, was bei der Methodendeklaration in geschweiften Klammern steht). Bei einem Feld ist es der Typ und der Name. Bei einer Klasse der Name und die Gesamtheit der öffentlichen Schnittstellen der ISBN public-Einträge.

Die Unterscheidung zwischen Klienten und öffentlicher Schnittstelle

Ein Programmteil, der eine öffentliche Schnittstelle einer Klasse nutzt, wird auch als Klient dieser Klasse bezeichnet.

Kontrakt

Der Kontrakt einer Dokumentation umfaßt die Aussagen, welche die Dokumentation über das Dokumentierte macht.

Die semantische öffentlicher Schnittstelle

Die semantische Schnittstelle besteht aus der öffentlichen Schnittstelle und den Kontrakten ihrer Dokumentation.

Ariane 5

Wenn die Einschränkungen des Moduls für die Ariane 4 gut dokumentiert gewesen wären, wäre der Fehler wahrscheinlich nicht passiert.

Daraus folgt, daß Module, welche nicht (gut) dokumentiert sind, nicht eingesetzt werden sollten, wenn die Probleme mit der Software gefährlich werden könnten.