Javadoc

Javadoc ist ein Dokumentationswerkzeug für Java-Quelltexte. Die für Implementierungsarbeiten bei SDQ standardmäßig verwendete Eclipse-Java-IDE unterstützt die Erstellung von Javadoc-Kommentaren und die Erzeugung einer Dokumentation im HTML-Format mit Javadoc. Diese Seite beschreibt die Verwendung von Javadoc und die bei SDQ vereinbarten Javadoc-Konventionen.

See PCM Development/Documentation for further documentation information.

Kommentieren mit Javadoc

Dieser Abschnitt beschreibt die Grundsätze des Kommentierens mit Javadoc. Ausführlichere Informationen liefern die Javadoc-Dokumentation und das Javadoc-Howto von Sun.

Kommentieren von Quellcodeelementen

Ein Javadoc-Kommentar wird einem Codeelement (Klasse, Feld, Konstruktor oder Methode) vorangestellt, um dieses Element zu beschreiben. Der Kommentar beginnt mit der Zeichenfolge /** und endet mit der Zeichenfolge */. Innerhalb des Kommentars beginnt jede Zeile mit einem Stern (*). Jeder Kommentar gliedert sich in drei Abschnitte:

Einleitungssatz: Der erste Satz ist eine Zusammenfassung des gesamten Kommentars bzw. eine Beschreibung des Elements in Kurzform. Er wird in der später erstellten Dokumentation hervorgehoben und ist daher besonders wichtig. Beim Erstellen der Dokumentation werden alle Zeichen des Kommentars bis zum ersten Punkt als Einleitungssatz interpretiert.
Beschreibung: Die ausführliche Beschreibung des Elements bildet den Hauptteil des Kommentars. Sie erfolgt im HTML-Format, so dass Formatierungen, Auflistungen und zusätzliche Elemente wie z.B. Hyperlinks und Grafiken (s.u.) mit Hilfe der üblichen HTML-Tags eingefügt werden können.
Block-Tags: Spezielle Angaben zum Element, die in der später erstellten Dokumentation gesondert dargestellt werden. Jede Angabe wird mit einem der vordefinierten Tags eingeleitet (z.B. die Beschreibung eines Methodenparameters mit @param)
- @author in classes: The author(s) of a class. If you contribute substantially to a class of somebody else (more than adding comments or fixing a small bug; for example if you add new functionality), please add your name to the authors tag.

Der Beschreibungsteil kann Links auf ergänzende Dateien (z.B. Grafiken, Quellcode-Beispiele, beliebige HTML-Dateien etc.) enthalten. Diese Dateien müssen in einem Unterverzeichnis doc-files des aktuellen Java-Packages abgelegt und innerhalb der Beschreibung durch entsprechende HTML-Tags referenziert werden.

Das folgende Beispiel stellt einen Javadoc-Kommentar dar:

/**
 * The first sentence gives a short definition of the element.
 * 
 * Following the short definition is a more detailed description
 * in HTML format. This description may have arbitrary length and
 * may contain structuring elements like lists, tables and images.
 *
 * If you want to include an image, place an image file in the
 * doc-files directory and reference it: <img src="doc-files/myImage.bmp">
 * 
 * You can also include a <a href="doc-files/myExample.java">reference</a>
 * to a source code file.
 *
 * @param myParam   this block tag describes a method parameter named myParam
 * @return          here we can describe the return value of a method
 * @see             a reference to another element's documentation
 */

Kommentieren von Java-Packages

Die oben beschriebene Kommentierung einzelner Quellcodeelemente ist oft zu feingranular, um größere Zusammenhänge, Architekturmuster etc. zu beschreiben. Daher bietet Javadoc auch die Möglichkeit, auf der Ebene von Java-Packages zu kommentieren. Die Kommentierung eines Packages erfolgt in einer HTML-Datei, die den Namen package.html trägt und sich direkt im Package-Verzeichnis befindet.

Der eigentliche Kommentar befindet sich innerhalb des <body>-Tags in der package.html-Datei. Wie bei der Kommentierung einzelner Quellcode-Elemente stellt der erste Satz (abgeschlossen mit einem Punkt) eine Kurzbeschreibung dar, gefolgt von einem ausführlichen Beschreibungsteil und eventuellen Block-Tags.

Das folgende Beispiel stellt eine Package-Beschreibung dar:

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
 <html>
   <head>
     <title>my.java.example package</title>
   </head>
   <body>
     The first sentence is the short definition of the package.
     This short definition is followed by a more detailed description of the contents of the package.
     Feel free to use HTML tags and, for example, to include images and source code files:
     <img src="doc-files/myImage.bmp">
     <a href="doc-files/myExample.java">myExample</a>
     @author Karl Mustermann
     @version 1.0
   </body>
 </html>

Erstellen einer Zusammenfassung

Die vorangegangenen Abschnitte beschreiben die Kommentierung einzelner Quellcodeelemente und Java-Packages. Darüber hinaus erlaubt Javadoc jedoch auch einen Kommentar auf höchster Ebene, um die dokumentierte Anwendung als Ganzes beschreiben zu können.

Dieser zusammenfassende Kommentar hat dasselbe Format wie ein Java-Package-Kommentar, wobei die den Kommentar enthaltende HTML-Datei hier beliebig benannt und plaziert werden kann. Der Name und Pfad der Datei werden für die Erstellung der Dokumentation explizit an Javadoc übergeben. In der erstellten Dokumentation wird die Zusammenfassung direkt auf der Startseite dargestellt.

Javadoc-Unterstützung in Eclipse

Die Eclipse-Java-IDE unterstützt den Entwickler bei der Eingabe von Javadoc-Kommentaren. Gibt man über einem Quellcodeelement die Zeichenfolge /** ein und betätigt die Eingabetaste, so wird das Gerüst des zugehörigen Javadoc-Kommentars automatisch erstellt. Das Erscheinungsbild dieses eingefügten Templates kann man über Window => Preferences => Java => Code Style => Code Templates selbst bestimmen.

Die Erstellung einer Dokumentation wird über Project => Generate Javadoc veranlasst. Der zugehörige Wizard bietet u.a. folgende Einstellungen:

Auswahl der zu dokumentierenden Elemente (evtl. mit Filterung gemäß Sichtbarkeit)
Ausgabeverzeichnis der Dokumentation
Titel der Dokumentation; Name und Pfad der Zusammenfassungs-Datei
Anzuwendende Stilbeschreibung
Aufnahme von Links auf referenzierte Archive und Projekte in die Dokumentation

Nach der Erstellung ist die Datei index.html im Ausgabeverzeichnis die Startseite der Dokumentation.

SDQ-Javadoc-Konventionen

Zur Sicherstellung der Softwarequalität der bei SDQ durchgeführten Implementierungsarbeiten sollen folgende Richtlinien eingehalten werden:

Quellcodeelemente (Felder, Methoden, Klassen) sind grundsätzlich zu kommentieren. Bei Verwendung des Eclipse-Plugins Checkstyle und der entsprechenden SDQ-Code-Konventionen wird die Vollständigkeit der Kommentierung automatisch überprüft.
Auch Pakete sind wie oben beschrieben zu kommentieren.
Neben der Dokumentation einzelner Elemente ist auch eine Beschreibung größerer Zusammenhänge und Entwurfsentscheidungen (vorzugsweise auf Paketebene) wünschenswert. Beschreibungen von Softwarearchitekturen sollten durch entsprechende Architekturbilder veranschaulicht werden.
Kommentare sind grundsätzlich in englischer Sprache zu verfassen.
@author in classes: If you contribute substantially to a class of somebody else (more than adding comments or fixing a small bug; for example if you add new functionality), please add your name to the authors tag.

Damit automatisch erstellte Kommentare bei überschriebenen Methoden nicht mit den SDQ-Code-Konventionen in Konflikt geraten, ist die Ersetzung des entsprechenden Code Templates durch das folgende Template (Window => Preferences => Java => Code Style => Code Templates) sinnvoll:

/** 
 * {@inheritDoc}
 */