Das Ergebnis dieses Postens können Sie mit jedem WWW-Browser anschauen und beurteilen. Es müssen jedoch einige Vorkehrungen getroffen werden, bevor sie überhaupt etwas Vernünftiges sehen können. Lesen Sie deshalb die Hinweise zu folgenden Themen durch bevor Sie mit der Arbeit beginnen.
Es sollten genügend Java-Dateien existieren, mit denen Sie im Laufe dieser Werkstatt gearbeitet haben. Falls Sie einmal unsere Lösung übernommen haben, haben Sie schon einfache Vorgaben, die Sie vielleicht noch ergänzen oder präzisieren müssen.
Wenn keine Optionen angegeben werden produziert javadoc aus einer .java-Datei vier HTML-Seiten.
Der grosse Nachteil der generierten HTML-Seiten ist, dass alle Links lokal sind. Dies bedeutet, dass der WWW-Browser beim Klicken auf einen Link nur innerhalb des aktuellen Verzeichnisses nach der neuen Seite sucht. Da aber bei jeder Dokumentation viele Links zu anderen Klassen generiert werden, bedeutet dies dass Ihre Dokumentation eigentlich im api-Verzeichnis gespeichert werden müsste. Wenn Sie immer das gleiche Verzeichnis für Ihre Dokumentationen brauchen, sind allerdings alle Links auf Ihre eigenen Dokumente in Ordnung. Links die auf Superklassen oder auf importierte Klassen der Standardbibliothek zeigen sind aber nicht brauchbar.
Zudem geht javadoc davon aus, das in dem Verzeichnis, wo die HTML-Seiten angelegt werden auch ein Unterverzeichnis images exisiert, das sämtliche Bilder enthält die nötig sind.
Die Generierung eines Index funktioniert offensichtlich nicht. Und die meisten Links auf der Seite tree.html zeigen auf api-Dokumente. Somit sind diese beiden Seiten kaum sinnvoll einsetzbar. Es empfiehlt sich daher die beiden Optionen -noindex und -notree zu verwenden.
Es gibt nun zwei Vorgehensweisen:
Arbeiten Sie am einfachsten mit der -d Option um Ihre Dokumentation ins api-Verzeichnis zu schreiben. Alle Links sollten einwandfrei arbeiten.
Es funktionieren nur diejenigen Links, die auf Ihre eigenen Dokumentationen zeigen. Alle anderen Links können Sie leider nicht brauchen.
Einige Bemerkungen noch zu den Kommentaren, die dann in Ihrer generierten Dokumentation erscheinen. javadoc erzeugt einen Eintrag für jedes von aussen sichtbare Element (Klassen, Felder und Methoden). Selbst wenn Sie keinen Kommentar dazuschreiben, erscheint einfach der Name ohne zusätzliche Bemerkung. Bei Deklarationslisten (z.B. int x, y, w, h) erscheint jedes Feld einzeln und zwar zweimal. Das erste Mal alphabetisch geordnet in einem Index. Es erscheint dort der erste Satz des Kommentars, genauer gesagt sämtlicher Text vor dem ersten Punkt (.). Das zweite Mal erscheinen die Felder in der Reihenfolge wie sie deklariert wurden und mit dem ganzen Kommentar der vor dieser Deklaration stand. Folgender Kommentar
/** * Pos. und Groesse des Fensters */ int x, y, w, h;
würde nicht viel Sinn machen. Das Ergebnis sähe wie folgt aus:
h w x y
public int x
public int y
public int w
public int h
Es sollten also Kommentare zu ganzen Deklarationslisten vermieden werden. Achten Sie auch darauf keine Abkürzungen im ersten Satz zu verwenden. Wenn Sie nun jedes Feld einzeln kommentieren, kann dies zu ziemlich unübersichtlichen Quelldateien führen. Vor lauter Kommentaren sieht man dann das Programm nicht mehr. Die Kunst liegt also darin, sich kurz zu fassen.
Java-Dokumentation - javadoc - Tips und Hinweise - Lösungsmöglichkeit
OOP - Werkzeuge - Referenzen - Fäden - Synchronisation - Applets - Dokumentation
Werkstatt - Bibliographie
