Klassenbeschreibungen

[Simon Reinhardt]

Hi!

z. B. halte ich die Dokumentationen von javadoc für zu "komplex" und dadurch
   unübersichtlich, wenn man sie das erste mal zu Gesicht bekommt. Die logische
   Strukturierung ist zwar gut, jedoch sind die Funktion und Parameter einer Methode erst
   über einen Link zu erreichen und stellt somit eine "Zerstückelung" der Information
   dar. Wer das erste mal javadoc-Output liest, ist eventuell etwas überfordert
   (zumindest habe ich diese Erfahrung etwas gemacht)

Naja, wie gesagt, man kann javadoc auch so erweitern, dass eigene Layouts produziert werden, durch die sich solche Mängel sicherlich ausmerzen lassen. Mit dem Aufwand einer solchen Erweiterung habe ich allerdings keine Erfahrung. Es ist aber wohl geplant, javadoc irgendwann mal beizubringen, XML als Output zu liefern. Und das ließe sich ja mit XSLT beliebig formen.
Aber auch, wenn javadoc sehr komplex erscheint - es liefert so viele Imformationen: über die vererbten Methoden, über Subklassen und implementierende Klassen, über die gesamte Vererbungsstruktur usw.
Nur, wie Martin schon gesagt hat: das alles bringt nichts, wenn die Beschreibungen des Programmierers nicht ausführlich genug sind. Ich habe schon so oft erlebt, dass in Suns eigenen Dokumentationen wichtige Informationen gefehlt haben. Und betet, dass Ihr nie mit einer Dokumentation von Apache-Programmierern zu tun bekommt! ;-) (Stichwort: Xalan)

Aber letztendlich kann es auch mit der besten Klassendokumentation noch schwer fallen, zu begreifen, was ein Programm tut. Letzt erst wollte ich über die javadocs herausfinden, wie der SAX-Parser zu benutzen ist. Finde da erst mal die Einstiegsklasse! Ohne zusätzliche Docs oder ein gutes Buch ist man hier verloren. :)

VG Simon