Howto: @pre, @post und @inv Tags in Javadoc
Man kann mit Javadoc eigene Tags definieren. Eine genaue Beschreibung findet sich hier. Auf dieser Seite folgt ein kurzes Howto, wie man @pre, @post und @inv Tags zu javadoc hinzufügt, einmal in der einfachen Variante und einmal in einer verbesserten Variante mit Taglets. Zum Schluss wird noch kurz gesagt, wie man das Generieren der Javadoc aus Netbeans, Eclipse, Maven und Ant heraus einrichten kann.Einfache Variante
Am einfachsten definiert man die Tags mit der -tag Option auf der Kommandozeile von javadoc:-tag pre:cm:"Preconditions:" -tag post:cm:"Postconditions:" -tag inv:t:"Invariants:" -encoding "utf-8" -charset "utf-8" -docencoding "utf-8"Die Struktur
-tag X:Y:Z bedeutet hierbei:
| X: | Der Name des Tags im Programmcode ohne das @. Zum Beispiel pre:Y:Z bedeutet die Definition von @pre im Code. |
| Y: | Dieser Parameter gibt an, an welcher Stelle sich der Tag im Code befinden darf. Pre- und Postconditions zum Beispiel nur(!) in Konstruktoren(c) und Methoden(m). Invarianten hingegen nur in Klassendefinitionen(t). Eine Liste alle Parameter ist hier zu finden. |
| Z: | Der Name in dem erstellten Javadoc. |
Dann kann man im javadoc-Kommentar z.Bsp. schreiben:
/**
* Klasse zum Verwalten von Benutzern
* @inv Alle dem System bekannten Benutzer haben ein nicht leeres Passwort
* @inv Alle dem System bekannten Benutzer haben paarweise verschiedene Anmeldenamen
* @author plamm_01
*
*/
public class UserManager {
/**
* Fügt einen Benutzer hinzu
* @param login Anmeldename des Benutzers
* @param pwd Passwort des Benutzers
* @pre Der Anmeldename ist noch nicht vergeben
* @pre Das Passwort ist nicht leer
* @post Der Benutzer ist dem System bekannt
*/
public void addUser(String login, String pwd) { ... }
...
}
Um die Invarianten und Vor-/Nachbedingungen schöner zu formatieren, kann man auch eigene Taglets benutzen:
Mit Taglets
Man lädt die Datei cbs_taglets.jar herunter, am besten in sein Home-Verzeichnis oder C:\ unter Windows. Dann gibt man die folgenden Kommandozeilenoptionen an-taglet PreTaglet -taglet PostTaglet -taglet InvTaglet -tagletpath "/u/plamm_01/WWW/sopra/cbs_taglets.jar"Wobei man tagletpath entsprechend anpassen muss, z.Bsp.
-tagletpath "C:\cbs_taglets.jar"
Nun sind die Invarianten und Vor-/Nachbedingungen in der generierten Dokumentation schöner formatiert.
Anmerkung: Man kann auf diese Weise die Formatierung im Javadoc beliebig anpassen. Leider ist die cbs_taglets.jar Datei etwas veraltet und sieht nicht mehr "schöner" aus.Integration in Netbeans
In Netbeans kann man die Javadoc mit dem Menupunkt Run->Generate Javadoc generieren. Der Menupunkt File->Project Properties öffnet einen Dialog. Dort findet man unter Build/Documenting die Einstellungen für Javadoc. Im Feld Additional Javadoc Options kann man die zusätzlichen-tag bzw. -taglet und -tagletpath Parameter eintragen.
Integration in Eclipse
Um die Dokumentation direkt aus eclipse zu generieren, gibt es den Menupunkt Project->Generate Javadoc. Dort kann man im dritten Schritt unter Extra Javadoc Options die zusätzlichen-tag bzw. -taglet und -tagletpath Parameter eintragen. Diese wird eclipse dann als Standardeinstellung für das Projekt verwenden.
Integration in Maven
Die Integration in Maven läuft über Plugins so:
...
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.10.1</version>
<configuration>
<tags>
<tag>
<name>pre</name>
<placement>mc</placement>
<head>Preconditions:</head>
</tag>
<tag>
<name>post</name>
<placement>mc</placement>
<head>Postconditions:</head>
</tag>
<tag>
<name>inv</name>
<placement>t</placement>
<head>Invariants:</head>
</tag>
</tags>
</configuration>
</plugin>
...
bzw.
...
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.10.1</version>
<configuration>
<additionalJOptions>
<additionalJOption>-taglet PreTaglet </additionalJOption>
<additionalJOption>-taglet PostTaglet </additionalJOption>
<additionalJOption>-taglet InvTaglet </additionalJOption>
<additionalJOption>-tagletpath /u/plamm_01/cbs_taglets.jar </additionalJOption>
</additionalJOptions>
</configuration>
</plugin>
...
Integration in Ant
Die Integration in Ant sieht so aus:
<property name="src.dir" value="src"/> <!-- Source Verzeichnis -->
<property name="build.dir" value="build"/> <!-- Build Verzeichnis -->
<property name="doc.dir" value="${build.dir}/doc"/> <!-- Javadoc Verzeichnis -->
<property name="lib.dir" value="lib"/> <!-- Externe Libraries -->
<path id="classpath"> <!-- Pfad zu externen jar-Files -->
<fileset dir="${lib.dir}" includes="**/*.jar"/>
</path>
<!-- Target zum erzeugen von Dokumentation -->
<target name="doc" description="Erzeugung von Javadoc.">
<mkdir dir="${doc.dir}"/>
<javadoc sourcepath="${src.dir}" destdir="${doc.dir}" classpathref="classpath"
encoding="utf-8" charset="utf-8" docencoding="utf-8">
<tag name="pre" description="Preconditions:" scope="methods,constructors"/>
<tag name="post" description="Postconditions:" scope="methods,constructors"/>
<tag name="inv" description="Invariants:" scope="types"/>
<!-- <taglet name="PreTaglet" path="${lib.dir}/cbs_taglets.jar" />
<taglet name="PostTaglet" path="${lib.dir}/cbs_taglets.jar" />
<taglet name="InvTaglet" path="${lib.dir}/cbs_taglets.jar" /> -->
</javadoc>
</target>
- Aktuelles
- Wochenplan (Kalender)
- Wochenplan (Liste)
- Wochenplan als ical
- Kolloquien
- Stellen FB10
- Stellen extern
- Bibliothek
- Buchrecherche
- Zeitschriftenrecherche
- Preprints
- Mathematical Reviews
- Zentralblatt für Mathematik
-
- Service
- Veranstaltungen buchen
- Ü-Leiter Bewerbung
- Rechnerwartung
- Raumbelegungsplan
- Raumreservierungen
- Personalverzeichnis
- Studieninfos
- Vorlesungsverzeichnis
- Prüfungsordnungen
