Suche
Power Tools Woche

JAutodoc: Javadoc automatisch generieren

Tam Hanna

Besonders im universitären Bereich ist es geradezu eine Pest: Jedes noch so kleine Beispiel muss aufwändig mit Javadoc-Kommentaren versehen werden. Ob diese Kommentare sinnvoll sind, ist irrelevant. Das ruft nach Automatisierung.

Wer mit Eclipse entwickelt, sollte sich JAutodoc als kleines Helferlein anlachen. Das Plug-in, das unter [1] heruntergeladen werden kann, erstellt die Dokumentation automatisch – und arbeitet dabei so genau, dass man auf den ersten Blick meint, die Javadoc-Kommentare wären von Hand erstellt. Zur effizienteren Installation bietet der Entwickler auch einen Updateserver an, der Eclipse das direkte Installieren aus dem GUI heraus (also ohne manuelles Herumkopieren) erlaubt. Dazu wählt man HELP | INSTALL NEW SOFTWARE und gibt ins Feld Work With den String http://jautodoc.sourceforge.net/update/ ein. Nach einem Druck auf ENTER wird JAutodoc zum Download angeboten und lässt sich nach Abnicken der Sicherheitswarnung automatisch installieren.

Wie geht das?

Nach dem obligatorischen Neustart der Entwicklungsumgebung ist das Plug-in einsatzbereit. Die einfachste Art des Einsatzes besteht darin, ein Projekt im Package Explorer rechts anzuklicken und im daraufhin erscheinenden Kontextmenü die Option JAUTODOC | ADD JAVADOC zu wählen. JAutodoc macht sich dann sofort an die Arbeit und versieht alle möglichen Stellen mit Kommentaren im Javadoc-Stil. Dabei agiert das Produkt teilweise überraschend intelligent. Zum Beispiel erkennt es init-Methoden anhand des Namens und versieht sie – wie im Beispiel gezeigt – selbsttätig mit einem passenden Kommentar:

/**
 * Inits the rapper.
 */
private void initRapper()

Die Namen normaler Methoden entstehen durch die Trennung der einzelnen „Wörter“ des Methodennamens. Das Verwenden von Camel Case hilft dem Plug-in bei der Identifizierung der Trennstellen. Übrigens werden auch Member-Variablen nach dem Schema „Namen splitten“ bearbeitet:

/**
 * Big boom.
 */
public void bigBoom()

Singleton-bezogene Funktionen erkennt das Programm ebenfalls selbsttätig – das Beispiel unten stammt wie die zuvor gezeigten Codesegmente aus einer JezzBall-Portierung für die BlackBerry-Plattform, die aus diversen Gründen niemals ausgeliefert wurde:

/**
 * Gets the single instance of BallZNoiseMaker.
 *
 * @return single instance of BallZNoiseMaker
 */
static public BallZNoiseMaker getInstance()
Mit Maß und Ziel

Obwohl das automatische Dokumentieren ganzer Projekte zweifellos reizvoll ist, erscheint dieses Feature in manchen Situationen als totaler Overkill. JAutodoc erlaubt aus diesem Grund auch das Kommentieren in kleinerem und wohlgezielterem Rahmen. Will man nur eine einzelne Datei kommentieren, klickt man sie im Package Explorer rechts an und wählt JAUTODOC | ADD JAVADOC aus. Noch gezielter kann man das Zielgebiet festlegen.

Advanced Autodoc

Obwohl die in JAutodoc enthaltene Intelligenz auf den ersten Blick mehr als beeindruckend wirkt, kann man trotzdem durch einige Stellschrauben „Feineinstellungen“ vornehmen. So ist es dem Plug-in zum Beispiel nicht möglich, den Namen des Entwicklers und seines Unternehmens zu erraten – generiert man dann einen Header, bekommt man einen „leeren“ Kommentar.

Die globalen Einstellungen des Plug-ins finden sich unter WINDOW | PREFERENCES | JAVA-> JAUTODOC. Am wichtigsten ist es, dort das Häkchen vor der Option ADD TODO FOR AUTO-GENERATED JAVADOC zu entfernen. Tut man dies nicht, garniert das Plug-in jede Datei mit einer To-do-Notiz, dass man das automatisch generierte Javadoc doch bitte ausfüllen möge.

Die drei Checkboxen im Feld Mode erlauben das Festlegen des Umgehens mit schon in den Dateien befindlicher Javadoc-Dokumentation. Mit Visibility und Filter wird festgelegt, welche Teile des Programms kommentiert werden sollen – so kann man zum Beispiel private-Elemente von der Kommentierung ausnehmen, wenn das im Unternehmen so gehandhabt wird.

In der Liste „Replacements for comment from element name“ darf man einige direkte Ersetzungen festlegen. So wird zum Beispiel das weiter oben besprochene Erkennen von Initialisationsroutinen dadurch möglich, dass es für init ein Inits the Replacement gibt. Wer eigene Replacements definieren will, kann das mittels des Add-Buttons tun.

Steht ein Upgrade der lokalen Arbeitsstation an, sollte man die Optionen IMPORT ALL und EXPORT ALL im Auge behalten. Sie erlauben das aufwandslose Übertragen der JAutodoc-Einstellungen über eine Textdatei.

Geschrieben von
Tam Hanna
Kommentare

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht.