Dokumentation mit JavaDoc

Warum JavaDoc?

Das Problem

Java kennt keine Header-Dateien, die .class-Dateien sind ihre eigenen Header (selbstbeschreibend)
Schnittstellen müssen aber dokumentiert werden, damit sie richtig verwendet werden können
Wir wollen den Source-Code nicht weitergeben, dort steht aber die Dokumentation der Schnittstelle

Die Lösung

Aus dem Source-Code eine HTML-Dokumentation generieren, die der Verwender der Klassen benutzen kann

In vielen Programmiersprachen (z. B. C++) gibt man für jede Klasse zwei Dateien weiter: zum einen die kompilierte Klasse und zum anderen eine sogenannte Header-Datei, die die Methoden beschreibt, die man von außen aufrufen kann. In der Header-Datei stehen alle Informationen dazu, wie man eine Methode verwendet.

Java hat sich für eine andere Lösung entschieden: hier schreibt der Compiler alle Informationen, die man zur Nutzung einer Klasse braucht, direkt in die kompilierte Klasse hinein. Man benötigt also nur die .class-Datei, um mit der Klasse zu arbeiten und sie zu verwenden.

In der .class-Datei findet sich aber nur die technische Beschreibung der Schnittstelle aber keine Informationen zu den Namen der Parameter und keine Dokumentation der Methoden. Beim Kompilieren gehen also die Kommentare, der Entwickler:innen im Quelltext, verloren. Damit stellt sich die Frage, wie man die Dokumentation der Methoden zum Verwender der Klasse transportiert.

Die Lösung findet sich in der JavaDoc: aus speziellen Kommentaren im Quelltext erzeugt ein Werkzeug HTML-Seiten mit Dokumentation, die man dann zusammen mit den kompilierten Klassen weitergeben kann.

Beispiel: JavaDoc Ausgabe

Wie funktioniert JavaDoc?

Spezielle Kommentare vor Klassen und Methoden
/** JavaDoc Kommentar */
Tags, um Informationen zu kennzeichnen

@author - Author der Klasse
@version - Version der Klasse
@throws - Wann eine Exception geworfen wird
@param - Parameter eine Methode
@return -Rückgabewert einer Methode
@see - Querverweis

Programm (javadoc): liest Klassen, wertet Tags aus und erzeugt Dokumentation

Methoden sollten im Allgemeinen durch einen Satz mit Verb beschrieben werden, der die Aktionen beschreibt, die von der Methode ausgeführt werden, z. B. „Gibt die Anzahl der Elemente in der Liste zurück.“

Klassen, Interfaces und Variablen werden eher durch einen Satz mit Nomen beschrieben, der erklärt, was sie darstellen, z. B. „Eine Liste von Elementen.“

Formatierung von JavaDoc

Der erste Satz des JavaDoc-Kommentars ergibt die Zusammenfassung für die Übersicht
Man kann HTML-Tags verwenden, um den Text zu strukturieren

<p>...</p>
<i>...</i>
<pre>...</pre>
<code>...</code>

Seit Java 5 gibt es spezielle JavaDoc-Tags, die viele der HTML-Tags überflüssig machen

{@code ... }
{@literal ... }

Als ersten Satz fasst das JavaDoc-Tool alle Zeichen am Anfang des Kommentars bis zum ersten Punkt auf, den ein Leerzeichen, Tab oder Zeilenende folgt auf. Dieser Teil wird dann in die Klassenübersicht übernommen und als Zusammenfassung der Methodenbeschreibung gewertet. Grundsätzlich sollten sich die Zusammenfassungen aller Methoden einer Klasse bzw. eines Interfaces unterscheiden.

Beispiel: JavaDoc von String

/**
  * The <code>String</code> class represents character strings. All
  * string literals in Java programs, such as <code>"abc"</code>, are
  * implemented as instances of this class.
  * <p>
  * Because String objects are immutable they can be shared. For example:
  * <p><blockquote><pre>
  *     String str = "abc";
  * </pre></blockquote><p>
...
  * @author  Lee Boynton
  * @see     java.lang.Object#toString()
  * @see     java.lang.StringBuffer
  * @since   JDK1.0
  */
public final class String
    implements java.io.Serializable, Comparable<String>, CharSequence
{

/**
  * Returns the <code>char</code> value at the
  * specified index. An index ranges from <code>0</code> to
  * <code>length() - 1</code>. The first <code>char</code> value of the
  * sequence is at index <code>0</code>, the next at index <code>1</code>,
  * and so on, as for array indexing.
  *
  * <p>If the <code>char</code> value specified by the index is a
  * <a href="Character.html#unicode">surrogate</a>, the surrogate
  * value is returned.
  *
  * @param      index   the index of the <code>char</code> value.
  * @return     the <code>char</code> value at the specified index of this string.
  *             The first <code>char</code> value is at index <code>0</code>.
  */
public char charAt(int index) {
...

JavaDoc und Pflichtübungen

Es wird erwartet, dass Sie Ihre Lösungen mit JavaDoc dokumentieren
alle öffentlichen Methoden und Interfaces müssen dokumentiert werden
fehlende oder unvollständige JavaDoc führt zu Punktabzügen