nicht angemeldet
Halihallo Martin und Simon
also neben dem Javadoc gibt es noch was ähnliches von MS für .NET Sprachen, allerdings XML basierend. Womit du es dann machst, ist aber relativ egal, auf das Endergebnis kommt es an.
Hat hierzu vielleicht jemand einen Link? - Wie sieht die Doku dort aus?
Wenn du ne Weile mit Java arbeitest, bzw. mit der Hilfe, wirst du feststellen, dass das beste Tool nichts nutzt, wenn man die Doku nebenher macht.
Full ACK. Und genau deshalb schreibe ich ein Dokumentationstool. Ich habe mich nur zu oft
bei der Handlung erwischt, dass ich gleich mit programmieren angefangen habe und mir
keine Gedanken zu den Informationen/-strukturen gemacht habe; nun, das ist vielleicht
etwas übertrieben, jedoch will ich genau dieses "code&fix"-Vorgehen unterbinden, indem
ich mich sozusagen zwinge erst eine Dokumentation (und den dadurch implizit vorher
getätigten Modellierungsarbeiten) zu schreiben. Der Code/Umsetzung folgt dann später.
Gestern hatte ich schon erste Versuche gestartet, den Perl-Code automatisch aus der
Dokumentation zu erstellen (die Package-Rümpfe).
Was mich an den Java-Hilfen (sei's nun Java selbst, oder Xalan, oder für andere Bibliotheken) stört, sind zu kurz gehaltene Beschreibungen der Methoden und ihrer Parameter, nichtssagende Beispiele, Sätze wie "see function above" (schön, die steht im Source oben. Nicht in dem, was Javadoc generiert), und Ähnliches. Da liegt die Krux, nicht ob man nun Javadoc nimmt, das .NET-Äquivalent, oder was Eigenes. Man braucht Selbstdisziplin.
Stimmt. Die ganze Dokumentation ist eben doch nur soviel wert, wie die Arbeit, die der
Programmierer dafür investiert hat, unabhängig von der Ausgabe des Programmes. Es geht
mir bei diesem Programm auch mehr darum, eine einfach zu verwaltende, unabhängige
Dokumentationsschnittstelle zu erstellen, um mir den Aufwand etwas zu reduzieren
(nicht jedes mal von neuem Gedanken zur Strukturierung der Dokumentation zu machen).
zu Simon: "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. :)"
genau das steht bei mir auch noch ganz weit oben. Eine reine Dokumentation der Klassen
und Vererbungshierarchien bringt wirklich nur dann etwas, wenn die Funktionsweise und
das Zusammenspiel der Komponenten bereits bekannt ist. Genau dies möchte ich auch in
mein "Tool" einfliessen lassen. Bevor also die Klassenbeschreibungen kommen, muss eine
grundlegende Dokumentation des ganzen "Systems" stattfinden; sozusagen der "Scope" des
Projektes und dann eine allgemein gehaltene Einführung mit Beispielen. Das vermisse ich
bei javadoc auch.
Viele Grüsse
Philipp