Klassendokumentationen schreiben

Java-Systeme bieten ein Werkzeug namens javadoc an, mit dem Schnittstellenbeschreibungen von Klassen aus Quelltexten generiert werden können. Die Dokumentation der Standardbibliothek ist beispielsweise aus den Quelltexten der Klassen mit Hilfe von javadoc erzeugt worden. In BlueJ kann man eine Klassendokumentation im Menü Tools-Project Documentation erzeugen lassen.

Die Dokumentation einer Klasse sollte mindestens die folgenden Punkte enthalten:

• den Klassennamen
• einen Kommentar, der den allgemeinen Zweck und die Eigenschaften der Klasse beschreibt
• eine Versionsnummer
• den Autorennamen

Die Dokumentation jedes Konstruktors und jeder Methode sollte enthalten

• den Namen der Methode
• den Ergebnistyp
• die Namen und Typen der Parameter
• eine Beschreibung des Zwecks und der Arbeitsweise der Methode
• eine Beschreibung jedes Parameters

In Java werden Kommentare für javadoc mit einer speziellen Zeichenfolge eingeleitet:

/**
* Dies ist ein javadoc-Kommentar.
*/

Wenn ein solcher Kommentar unmittelbar vor einer Klassendefinition steht, wird er als Klassenkommentar aufgefasst. Wenn er unmittelbar vor der Signatur einer Methode steht, wird er als ein Methodenkommentar aufgefasst. Für Java stehen in Verbindung mit javadoc einige Schlüsselwörter zur Verfügung, mit denen die Dokumentation formatiert werden kann. Diese Schlüsselwörter beginnen immer mit dem Symbol @:

@version
@author
@param
@return

Die Schlüsselwörter @author und @version finden sich üblicherweise in jedem Klassenkommentar. Die Schlüsselwörter @param und @return finden sich in Methodenkommentaren von Methoden, die Parameter und/oder einen Rückgabewert haben.

» drucken: pdf | html