Eigene Klassen einbinden

[Daniel N.]

Hallo,

Es sollte einen Zurückübersetzer geben, der aus dem Javadoc-HTML ein
(gerne auch binäres) Format erzeugt, das vollständig integriert in
der IDE verwendet werden kann.

Ein "Zurückübersetzer" ist absolut unnötig. Die Javadoc-HTML-Dokumentation liegt in einer wohl definierten Struktur vor! Die Struktur ist so angelegt, dass sich der Link zur entsprechenden HTML-Seite bis auf Methoden-Ebene ableiten lässt.
Z.B.:
Die Klasse "de.test.hello.HelloWorld" mit der Methode "sayHello()"
landet in der HTML-Datei im Verzeichnis "de/test/hello/HelloWorld.html#sayHello().

Im Javadoc-Kommentar in der Klasse kann man die Methode wie folgt verlinken:
/**
{@link de.test.hello.HelloWolrd#sayHello()}
*/
javadoc generiert den entsprechenden Link.

Auch wen ich selber Eclipse nutze und die IDE gut finde... Eine gute IDE kann selbsverständlich auch die Api-Dok verwenden!
D. h. die Informationen, die man in Eclipse als gelben "Notizhilfe-Popup" bekommt, sollten auch aus einer javadoc kommen können! Das kann eclipse leider nicht, hier ist ein "Source-Code-Attachment" erforderlich.
Das ist bei anderen IDEs nicht nötig, z. B. JBuilder.

Auch dazu muss die Doku zunächst einmal bekannt sein. Nur woher? Die Einbindung irgend einen JAR-Files mit diversen CLASS-Dateien lässt noch lange nicht darauf schließen, wo die Verwendung dokumentiert ist - bzw. ob überhaupt.

Man benötigt natürlich den Ort, wo die API-Doc abgelet ist.

Dafür muß eine Konvention existieren, klar. Aber wofür gibt es denn
die Manifest-Datei? Dort ließe sich doch eine Dokumentations-Datei
im JAR referenzieren.

Die Manifest-Datei hat andere "Aufgaben" und ist für diesen Zweck nicht geeignet/gedacht.

Für einzelne Class-Dateien muß dann eben die IDE die Zuordnung
ermöglichen. So handhabt Eclipse dies ja auch heute schon, wenn man
die Sourcen an eine JAR-Datei "bindet".

S.o. Das sollte auch ohne Source-Attachment gehen!

[Doku im externen Browser vermeiden]
Ja: Quellcode suchen! ;-)

Bei vielen kommerziellen Produkten bekommt man nicht nur keinen Quelltext, sondert dort sind die Sourcen meistens auch durch einen Obfuscator unlesbar gemacht worden, so dass man keinen Decompiler mehr nutzen kann!

Bei uns klappt das (meistens), weil wir gewöhnlich nur Projekte verwenden, deren Quellcode uns zur Verfügung steht; sei es nun wegen Open Source oder durch Einkauf. Trotzdem habe ich schon oft genug überlegt, ob ich jetzt wirklich wieder ein externes Projekt auschecken möchte oder es mir doch antue, die Doku im Netz zu suchen. Schön ist es nicht.

Mir ist eine vernünftige Schnittstelle mit einer guten Dokumentation wesentlich lieber als in den Quellcode gucken zu müssen!
Eine schlechte und dazu schlecht dokumentierte Schnittstelle lässt ein Produkt in einem sehr schlechtem Licht erscheinen!

Du meinst, weil das dann bei einem Full (Re)build wieder alles
mitkompiliert werden muß? Ja, das ist wirklich ein Nachteil. (Ich wüßte
jetzt spontan nicht mal, ob man einzelne Projekte aus dem Build-
Vorgang ausschließen kann, und trotzdem noch die Quellen zur
Dokumentation verwenden kann.)
Oder dauert es dir einfach zu lange, das Projekt auszuchecken, wenn

"Fremde" Bibliotheken sollten auf gar keinen Fall kompiliert werden, auch wenn es open source ist und man die Sourcen hat!
Das macht keinen Sinn, da es unnötig ist! Bei Java gibt es diese Abhängigkeiten nicht (wie es z. B. bei c++ der Fall ist).

Viele Grüße
Daniel