Power Tools Woche

JAutodoc: Javadoc automatisch generieren

Tam Hanna
Template me

Will man das Aussehen der von JAutodoc automatisch eingefügten Kommentare anpassen, schlägt die Stunde des unter JAUTODOC | TEMPLATES zu findenden Editors. Als Template-Sprache kommt die vom Apache-Projekt bekannte Velocity zum Einsatz – für kleinere Änderungen muss man sich allerdings nicht voll einarbeiten.

Die Grundlage fast aller Ersetzungen ist das Element ${e}. Gibt man es ein und nach dem „e“ einen Punkt, erscheint automatisch ein AutoComplete-Fenster mit möglichen „Abwandlungen“. Unter PROPERTIES kann man zusätzliche Eigenschaften deklarieren. Will man beispielsweise den Namen der eigenen Firma als Template-Parameter verwenden, klickt man im PROPERTIES-Dialog auf ADD. Daraufhin vergibt man als Namen z. B. TmgnParamTamoggemon. Im Feld Value gibt man den Ersatzwert ein, im Fall des Autors wäre das „Tamoggemon Holding k.s.“. Ab diesem Zeitpunkt kann dieses Feld in Templates verwendet werden. Will man zum Beispiel den Template der Main-Methode um den Firmennamen erweitern, sieht der resultierende Code wie in Listing 1 aus.

Listing 1

/**
 * The main method, created by ${TmgnParamTamoggemon}.
 * 
 * @param ${e.g(1)} the arguments
 */

Wechselt man im Template-Editor in die Preview-Ansicht, so sieht das Resultat so aus:

/**
 * The main method, created by Tamoggemon Holding k.s.. 
 * 
 * @param args the arguments
 */

Übrigens: Das Erstellen von Parametern ist auch dann sinnvoll, wenn man den Namen nur sehr selten verwendet. Man weiß nämlich nie, wann sich Firmennamen etc. ändern – im Falle des Falles ist es eine große Erleichterung, wenn man nicht neben all den rechtlichen Umstellungen auch noch auf „Namensjagd“ gehen muss.

Ein besserer Header

Mit diesem Wissen bewaffnet, wollen wir uns einen „besseren“ Header zusammenbasteln. Das Template für den Header sitzt aus dem Autor unerklärlichen Gründen nicht in Templates, sondern im weiter oben besprochenen Hauptdialog des Einstellungseditors. Nach dem Markieren der Checkbox ADD FILE HEADER klickt man auf EDIT., um das Template festzulegen. Fürs Erste ist folgendes Template durchaus brauchbar:

/*
 * File: ${file_name}
 * 
 * Property of ${TmgnParamTamoggemon}
 * 
 * Copyright: ${year}
 */

Fügt man einer Datei mittels JAUTODOC | ADD HEADER einen Header hinzu, entsteht folgendes Resultat:

/*
 * File: BallZNoiseMaker.java
 * 
 * Property of Tamoggemon Holding k.s. 
 * 
 * Copyright: 2012
 */
Der Dokumentationskomplettierer

JAutodoc nistet sich auch in der Suchfunktion von Eclipse ein. Der Aufruf von SEARCH | JAUTODOC. öffnet eine adaptierte Version des Suchdialogs. Dort kann man das Plug-in anweisen, nach verschiedenen Fehlern in den Dokumentationskommentaren zu suchen.

Was auf den ersten Blick sinnfrei klingt, kann insbesondere bei großen Projekten lebensrettend sein. In der Hitze des (programmatischen) Gefechts vergisst man sehr schnell, einen Kommentar einzufügen – Murphys Gesetz garantiert in diesem Fall, dass der von diesem Kommentar abhängige Entwickler in einer anderen Zeitzone sitzt und deshalb einen Arbeitstag verliert. Zu guter Letzt lässt sich JAutodoc sogar in Ant integrieren. Wer sich dafür interessiert, findet unter [2] weitere Informationen zu Syntax und Funktionalität.

Fazit

Der Autor kennt eine Vielzahl von Entwicklern, die JAutodoc mit großem Erfolg an diversen Universitäten einsetzen. Bis jetzt hat sich kein Dekan darüber beschwert bzw. Plagiarismus unterstellt – und wenn doch, reicht in der Regel die Androhung einer Rufschädigungsklage zur Wiederherstellung des Respekts vor dem Steuerzahler. Wer Javadoc produktiv einsetzt, profitiert ebenfalls. Die von JAutodoc erstellten „Skelette“ ersparen jede Menge Tipparbeit, da man statt der kompletten Struktur nur noch die Beschreibungen eingeben muss. Deshalb nochmals kurz zusammengefasst: Wer mit Javadoc zu tun hat, sollte dieses kostenlose Plug-in installieren.

Tam Hanna befasst sich seit der Zeit des Palm IIIc mit Programmierung und Anwendung von Handcomputern. Er entwickelt Programme für diverse Plattformen, betreibt Onlinenewsdienste zum Thema und steht unter tamhan@tamoggemon.com für Fragen, Trainings und Vorträge gern zur Verfügung.
Geschrieben von
Tam Hanna
Kommentare

Schreibe einen Kommentar

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