Apache Ant: JavaDoc erstellen

In diesem Tutorial möchte ich erläutern wie man eine JavaDoc Dokumentation mit Apache Ant erzeugt.

Apache Ant dient zum erstellen von Build Scripten und ist in den letzten Jahren durch die Tools Apache Maven, Gradle usw. immer weiter in den Hintergrund gerutscht. Leider zu unrecht denn mit Apache Ant welches in zbsp. Eclipse integriert ist, ist es ein leichtes kleine Scripte zu erstellen und sogar eigene Task zu programmieren.

Wie man ein Ant Script aufbaut habe ich bereits im Tutorial Ant Build Script erläutert, daher möchte ich hier nun auf den Task „JavaDoc“ eingehen.

Vorbedingungen

Damit man den JavaDoc Task verwenden kann muss man die Umgebungsvariable „JAVA_HOME“ auf ein Oracle Java JDK einrichten. Sollte die Umgebungsvariable auf eine JRE zeigen so wird dieses mit der Fehlermeldung „Javadoc failed: java.io.IOException: Cannot run program „javadoc.exe“:…..“  quitiert.

Ant Task JavaDoc

Die ausführliche Dokumentation zum Apache Ant JavaDoc Task findest du unter https://ant.apache.org/manual/Tasks/javadoc.html ich möchte hier jedoch ein einfaches aber in der Praxis nützliches Beispiel zeigen

 Der JavaDoc Task benötigt zum ausführen mindestens folgende Attribute:

sourcepath

In diesem Attribut wird der Ablageort der Quellcode Dateien definiert.

destdir

Dieses Attribut definiert den späteren Ablageort für das generierte JavaDoc.

Optionale Attribute

Zusätzlich kann man noch definieren was alles in die JavaDoc einfließen soll.
In meinem Beispiel habe ich den Author, die Version sowie alle Private deklarierten Variablen, Methoden und Klassen eingeschlossen.

windowtitle

Den Titel der JavaDoc Dokumentation kann man mit dem Attribut „windowtitle“ anpassen.
Hier kann man einen beliebigen Wert wählen oder aber auch die Ant Properties mit ${ant.project.name}

Ausführen des Targets

Das Ant Target kann wenn es als „default“ eingestellt wurde 

auf der Kommandozeile einfach mit „ant“ ausgeführt werden.

Apache ANT - ausführen des Target "generateJavaDoc"
Apache ANT – ausführen des Target „generateJavaDoc“

Warnings beim ausführen

Beim Ausführen des Target kann es unter umständen zu warnings führen wie:

Dieses liegt vielmehr daran wenn zwar ein JavaDoc Kommentar angefangen wurde aber nicht fertiggestellt wurde.

In diesem Beispiel fehlt die Deklaration des Rückgabewertes im JavaDoc Kommentar der Methode „getGreeting“.

Download

Im nachfolgenden möchte ich nun das Eclipse Projekt zum Download anbieten.

 

Ausblick

Wie eingangs erwähnt ist Apache Ant schon deutlich in die Jahre gekommen und mit Apache Maven hat man zusätzlich noch die Möglichkeit seine Abhängigkeiten (Dependencies) zu verwalten und das Projekt zu bauen, zu testen und die Dokumentation zu erstellen und noch vieles mehr.  Sicherlich kann man die Abhängigkeiten in einem Apache Ant Projekt mit Apache Ivy verwalten aber das währe dann doch noch älterer Kram welchen ich hier nicht weiter vertiefen möchte.

 

 

 

 

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.