Das Todo Doclet

Um dieser Umständlichkeit abzuhelfen, beschloss ich, mich einmal dem Thema Doclets zu widmen. Bisher hatte ich aus Respekt vor der Komplexität dieser API immer zurückgeschreckt, doch ein Blick in die Doku belehrte mich eines Besseren. Und so entstand innerhalb einer knappen Stunde (ich war wirklich gut :-)) dieses Todo-Doclet, welches ich hiermit zur freien Verwendung ins Netz stelle.

Implementation:
Eigentlich besteht das Todo-Doclet aus vier Teilen, die zusammen wirken müssen. Da wäre zunächst javadoc selbst. Dieses ist Teil des JDKs und ist überall mit diesem verfügbar. Der zweite Teil ist das Doclet, welches im Zuge eines javadoc-Laufes über die Klassen rennt und die dort vorhandenen Todos in eine XML-Datei schreibt. Der dritte Part wird von einem XSL-Stylesheet übernommen, welches aus dem XML eine HTML-Ausgabe erzeugt. Dies kann mit einem dazu fähigen Browser durchgeführt werden (z. B. dem Internet Explorer) durch einfachen Doppelklick auf die XML-Datei. Dazu müssen sich die beiden Dateien ( todo.xml und todo.xsl ) aber im gleichen Verzeichnis befinden.

Wer sich mit XSLT auskennt kann sich leicht - basierend auf dem hier vorgestellten Stylesheet - eigene Ausgaben erzeugen. CSV, RTF oder jedes andere Textformat sind möglich, deswegen habe ich die darstellungsunabhängige Form der XML-Notation gewählt.

Anwendung:
Zunächst gilt es, den Quellcode in ein Verzeichnis auf der Platte auszupacken. Bei der Durchsicht mit einem Editor werdet Ihr merken, dass die Klasse ListTodos.java bereits selber mit @todo -Tags versehen ist. Sie wird auch unser Beispiel begleiten.
Das Kompilieren der Java-Klasse funktioniert nur, wenn das Archiv tools.jar im Klassenpfad enhalten ist. Unter DOS sieht der entsprechende Aufruf zum setzen des CLASSPATH ähnlich aus wie dieser:

c:\doclet\set CLASSPATH=%CLASSPATH%;.;c:\JDK1.3.1\lib\tools.jar

Danach kann die Klasse einfach mittels:

c:\doclet\javac ListTodos.java

kompiliert werden.

Zum Test des Doclets wird jetzt javadoc aufgerufen:

c:\doclet\javadoc -private -doclet ListTodos *.java

Jetzt werden alle in diesem Verzeichnis befindlichen Java-Dateien auf Todos hin untersucht. Das Ergebnis dieser Untersuchung landet in der Datei todo.xml. Zur besseren Übersicht habe ich hier ein paar TABs eingefügt.

<?xml version="1.0" encoding="iso8859-1"?>
<?xml-stylesheet type="text/xsl" href="todo.xsl"?>
<control>
	<class name="ListTodos">
		<todo>Einbau der Kommandozeilenparameterübergabe</todo>
		<todo>Verarbeitung von HMTL Entities ermöglichen</todo>
		<method name="start">
			<todo>Verwenden eines Kommandozeilenparameters für die Ausgabedatei</todo>
			<todo>Verwenden eines Kommandozeilenparameters für das Stylesheet</todo>
		</method>
		<method name="writeContents">
			<todo>Ausgabe des Packagenamens</todo>
		</method>
	</class>
</control>

Ein einfacher Doppelklick im Windows Explorer auf diese Datei startet den Internet Explorer, der daraufhin die Datei todo.xsl sucht und öffnet, um das Layout dieser Daten zu generieren. Ergebnis ist eine HTML-Seite:

Todos

Diese Tabelle lässt sich vom Browser aus drucken und in Papierform als Checkliste verwenden. Genausogut ließe sich die XML-Datei im CVS versionieren. Es ist außerdem möglich, den ganzen Task als Target unter ANT zu verwenden und so mit jedem Build eine Übersicht über die Todos des Projekts zu bekommen.

Wenn ein Entwickler eine Aufgabe erledigt hat, so kann er sie einfach aus der Doku der Klasse oder Methode löschen und so verschwindet sie auch aus der Todo-Liste nach dem nächsten Build oder Javadoc-Lauf.

Verbesserungspotential:
Verschiedene Punkte zur Verbesserung/zum Ausbau liegen nahe:

• Einbau von weiteren Merkmalen in die Todo-Zeile zur Dokumentation der Erledigung (Done, Approved) im Sourcecode.
• Einbau des Stylesheet-Renderings direct in das Doclet, um als Ausgabe HTML zu erzeugen und damit nicht auf den Internet Explorer als Viewer angewiesen zu sein.

Weitere Vorschläge nehme ich gerne in diese Liste auf.

Ich würde mich freuen, wenn Du mich benachrichtigtest , falls Du diese Dinge erledigen möchtest oder bereits erledigt hast, sodass das Doclet hier weitergepflegt werden kann.

Eine tolle Sache hat Christof Glose auf seiner Homepage zur Verfügung gestellt. Der sogenannte ToDo-Listener durchsucht alle Java-Files unterhalb eines Verzeichnisses nach @todo-Tags und stellt diese Übersichtlich dar. Hier braucht man keinen Javadoc-Lauf anzustoßen, um die neueste Version der ToDos zu bekommen, dafür kann man die Ergebnisse aber auch nicht auf einer Webseite zur Verfügung stellen. Eigentlich ist das die ideale Ergänzung zum ToDo-Doclet für den Betrieb während des Codings.