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
<property name="srcDir" value="../src/" />
<property name="docDir" value="../javaDoc" />
<path id="build.path">
<!-- pathelement location="libs welche benötigt werden" / -->
</path>
<target name="generateJavaDoc">
<delete dir="${docDir}" />
<mkdir dir="${docDir}" />
<javadoc sourcepath="${srcDir}"
destdir="${docDir}"
packagenames="*.*"
author="true"
private="true"
version="true"
windowtitle="${ant.project.name}">
<classpath refid="build.path" />
</javadoc>
</target>
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
<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?> <project name="MyAntProject" default="generateJavaDoc" basedir=".">
auf der Kommandozeile einfach mit “ant” ausgeführt werden.
Warnings beim Ausführen
Beim Ausführen das Target kann es unter Umständen zu warnings führen wie:
[javadoc] Standard Doclet version 1.8.0_152 [javadoc] C:\Users\e8xf9k0\wks_planen_useranalyse\MyAntProject\src\de\draegerit\myantproject\Main.java:24: warning: no description for @return [javadoc] Building tree for all the packages and classes... [javadoc] * @return [javadoc] ^ [javadoc] Building index for all the packages and classes...
Dieses liegt vielmehr daran, wenn zwar ein JavaDoc Kommentar angefangen wurde aber nicht fertiggestellt wurde.
/**
*
* @return
*/
public String getGreeting() {
return greeting;
}
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äre dann doch noch älterer Kram welchen ich hier nicht weiter vertiefen möchte.