Gibt es gute und moderne Alternativen zu Javadoc? [geschlossen]

Seien wir ehrlich: Sie müssen kein Designer sein, um zu sehen, dass Standard- Javadoc hässlich aussieht .

Es gibt einige Ressourcen im Web, die neu gestaltetes Javadoc anbieten. Das Standardverhalten repräsentiert jedoch das Produkt und sollte genauso gut aussehen.

Ein weiteres Problem ist die Tatsache, dass die Benutzerfreundlichkeit von Javadoc im Vergleich zu anderen ähnlichen Ressourcen nicht auf dem neuesten Stand ist.

Besonders große Projekte sind mit der Schnellsuche von Firefox schwer zu navigieren.

Praktische Frage:
Gibt es eigenständige (Desktop-) Anwendungen, die in der Lage sind, vorhandene Javadoc-Dateien benutzerfreundlicher zu durchsuchen als ein Browser?
Ich denke an etwas wie Monos Dokumentationsbrowser.

Theoretische Frage:
Weiß jemand, ob es Pläne gibt, Javadoc irgendwie standardisiert weiterzuentwickeln?
BEARBEITEN: Ein nützlicher Link zum Sun-Wiki zu diesem Thema .

Ich habe ein Markdown (Java) -Doklet erstellt, das Quellkommentare in Markdown-formatiertem Text aufnimmt und dieselben HTML-Javadocs erstellt.

Das neue Doclet führt auch einige Neugestaltungen des Textes durch, aber der generierte HTML-Code wird zu diesem Zeitpunkt nicht geändert.

Damit können die Probleme mit HTML-in-Java-Kommentaren behoben werden, die wahrscheinlich das größte Usability-Problem mit dem aktuellen Javadoc darstellen.

Ich denke nicht, dass die Konzepte von Javadoc veraltet sind. Soweit ich sehen kann, wurzeln diese Konzepte vor Jahren in einem Produkt namens doxygen, das noch für andere Sprachen verfügbar ist (dh Objective-C, wo es häufig verwendet wird). Auch dies hat seine Vorgänger - werfen Sie einen Blick auf die Programmierumgebung, mit der Donald Knuth TeX ( Literate Programming ) erstellt.

Trotzdem ist es eine faszinierende Idee, eine einzige Quelle für Programmcode und Dokumentation zu haben.

Darüber hinaus kann die Präsentation der Dokumentation mithilfe eines vom JavaDoc-Tool unterstützten Plug-In-Systems an Ihre speziellen Anforderungen angepasst werden. Sie können (wie wir) ein Plug-In bereitstellen, das direkt in einer Datenbank veröffentlicht wird, auf die direkt über das Web zugegriffen werden kann. Mithilfe von Kooperationen kann jeder zusätzliche Kommentare oder Erläuterungen zur Dokumentation abgeben, die möglicherweise wieder in die ursprüngliche Quelle gelangen.

Javadoc ist das beste System zur automatischen Generierung von Quellcode, das ich je gesehen habe. Ein großer Teil davon ist, dass es so einfach ist - ich kann Javadocs sogar mit meinem 5 Jahre alten Handy durchsuchen, wenn ich möchte! Ich stimme zwar zu, dass ein kleines Facelifting angebracht sein könnte, und insbesondere JDK ist ein Problem beim Durchsuchen, aber ich würde es nicht wagen, das Rad vollständig neu zu erfinden, da wir derzeit eine RESTful, einfach zu verwendende Lösung für ihren Zweck haben, die funktioniert fast überall.

Ich habe kürzlich eine E-Mail erhalten, dass Sun an der Modernisierung der Javadoc-HTML-Ausgabe arbeitet. Aus dieser Mail:

Wir schlagen Verbesserungen an javadoc / doclet für JDK7 vor. Die Projekt-Wiki-Seite befindet sich unter http://wikis.sun.com/display/Javadoc/Home . Im Rahmen der vorgeschlagenen Verbesserungen wird die Benutzeroberfläche der Javadoc-Ausgabe überarbeitet. Die neuen Design-Screenshots werden in das Projekt-Wiki hochgeladen. Das Javadoc-Ausgabe-Markup wird so geändert, dass es gültige HTML- und WCAG 2.0-kompatibel ist.

Dort wird also definitiv noch gearbeitet, auch wenn es etwas spät ist. In meinen Augen ist einer der größten Nachteile von Javadoc jedoch die sehr enge Kopplung mit HTML. Viele Klassen haben Javadoc, das wörtliches HTML enthält und sich darauf verlässt, dass die Ausgabe auch HTML ist. Leider, aber das wird sich nicht ändern, denke ich. Dies bedeutet jedoch, dass es den Entwicklern freigestellt ist, alles, was sie wollen, in HTML aufzunehmen, was genauso gut ungültig, nicht wohlgeformt usw. sein kann. Die Anpassung der Ausgabe des Javadoc-Tools ist also nur ein Teil davon, der andere hat gewonnen. ' t und kann sich nicht ändern und bleibt somit.

Was das Durchsuchen der Dokumentation angeht, finde ich auch die HTML-Dokumentation etwas unhandlich. Normalerweise verwende ich die Javadoc-Ansicht in Eclipse. Es hat auch Nachteile (langsam und man kann nicht wirklich suchen), aber es ist für die meisten Dinge gut genug.

Persönlich finde ich Javadoc immer noch sehr nützlich. Zumal es standardisiert ist. Ich kenne keinen wichtigen Dokumentationsstil, den ich leichter navigieren kann (das mag sehr subjektiv sein, aber ich persönlich finde es zum Beispiel schrecklich, MSDN zu verwenden).

Für die Suche: Verwenden Sie den Javadoc-Suchrahmen , um die Verwendung von Javadoc aller Art erheblich zu vereinfachen. Es ist als Userscript für Firefox und als Google Chrome-Erweiterung verfügbar .

Um Ihre praktische Frage zu beantworten, habe ich gegoogelt und Freunde gefragt und mir diese ausgedacht. Forrestdoc, Doclet und Sauerstoff.

Die zweite Frage, ich würde sagen, ja, es ist nicht sehr "Web-oh-twoeye", aber zumindest ist es garantiert, dass Sie in einer Offline-Umgebung arbeiten, und es ist klein genug, um zusammen mit Ihrer API geliefert zu werden. Ich verzichte auf die Verwendung von Frames, aber dann funktioniert es ziemlich gut für Javadoc. Ich habe keine Pläne gesehen, es zu ändern. Eclipse unterstützt Javadoc beim Lesen, Interpretieren und Generieren.

Vielleicht möchten Sie das weniger aggressiv und anmaßend formulieren. Den meisten Menschen ist es egal, wie eine technische Ressource aussieht, und "Es ist nicht Web 2.0 genug!" klingt nach vapid marketroidspeak.

Und was genau würden Sie als "brauchbarer" betrachten? Persönlich hätte ich definitiv gerne eine Volltextsuche und einen besseren Nutzungsbrowser, und AJAX könnte wahrscheinlich dabei helfen.

Das Schöne an JavaDoc ist, dass es das Gegenteil von veraltet ist - es ist willkürlich erweiterbar. Warum schreiben Sie nicht ein Doclet , das die Art von API-Dokument erstellt, die Sie möchten?

Warum dies bisher noch niemand getan hat (was anscheinend der Fall ist), ist unklar - vielleicht fühlt sich niemand so stark dabei wie Sie.

Es gibt ein DocBook-Dokument. DocBook ist ein umfangreicherer Dokumenttyp als (X) HTML und eignet sich besser zur Beschreibung technischer Inhalte. Aus der DocBook-Quelle können Sie alle möglichen Ausgabeformate generieren.

Ich persönlich hätte gerne einen besser lesbaren Standard für "Kommentardokumentation" als den HTML-JavaDoc (und damit den Tag-Wieldy).

Zum Beispiel wäre MarkDown, wie es hier verwendet wird, ausgezeichnet, in der Quelle lesbar und außerhalb der Quelle gut formatiert.

Ich stelle mir vor, dass mit dem aktuellen JavaDoc viele Leute JavaDoc-Kommentare verwenden, aber nicht so weit dokumentieren, wie sie könnten. Ich bin sicher, dass jeder das Online-JavaDoc einer API durchsucht hat, das nicht oder kaum dokumentiert ist und daher weitaus schwieriger zu verwenden ist, als es sein sollte.

Dies wird nicht durch Code-Neuformatierer (z. B. innerhalb von Eclipse oder möglicherweise beim Festschreiben der Quelle) unterstützt, die alle lesbaren Strukturen, die Sie möglicherweise in einen JavaDoc-Kommentar (z. B. eine Liste von Elementen) eingefügt haben, vollständig in einem großen Textblock zerstören. es sei denn, Sie verwenden buchstäblich zwei Wagenrückläufe, wo Sie einen verwenden möchten).

Weiß jemand, ob es Pläne gibt, Javadoc irgendwie standardisiert weiterzuentwickeln?

Das entsprechende JSR (JSR 260), das Verbesserungen für Javadoc spezifiziert, wurde (vorerst) aus JDK 7 abgewählt. Ein Überblick über das, was geplant war (von dieser Seite ):

Aktualisieren Sie Javadoc, um eine umfangreichere Anzahl von Tags bereitzustellen, die eine strukturiertere Darstellung der Javadoc-Dokumentation ermöglichen. Diese JSR umfasst: Kategorisierung von Methoden und Feldern, semantischer Index von Klassen und Paketen, Unterscheidung von statischen, Factory-, veralteten Methoden von gewöhnlichen Methoden, Unterscheidung von Eigenschaftszugriffsberechtigten, Kombinieren und Aufteilen von Informationen in Ansichten, Einbetten von Beispielen und allgemeinen Anwendungsfällen, und mehr.

Die allgemeinen Aussichten für JDK 7 sind ziemlich düster .

JavaDoc selbst ist äußerst flexibel, da Sie das Standard-Doclet durch ein benutzerdefiniertes Doclet ersetzen können, um etwas bereitzustellen, das den spezifischen Anforderungen Ihres Projekts entspricht.

In dem Projekt, an dem ich gearbeitet habe, haben wir ein HTML / XML-basiertes Dokumentationssystem (mit clientseitigem XSLT 2.0 unter JS) für unser Produkt mit vollständig integriertem JavaDoc erstellt. Zu diesem Zweck wurde ein benutzerdefiniertes Doclet verwendet, um JavaDoc-Daten in XML zu erstellen. Dabei wurde eine Tagsoup verwendet, um sicherzustellen, dass auch HTML-Markups in Codekommentaren gut geformt waren.

Auf diese Weise konnten wir eine interaktive Benutzererfahrung mit einer einseitigen App (ähnlich einem Desktop-Tool) bereitstellen, jedoch alle über den Browser - ohne serverseitigen Code / Infrastruktur. Der Viewer enthielt Standardfunktionen wie Suche, Baumnavigation usw.

Hier ist ein Link zu einem Beispieleinstiegspunkt in der ziemlich umfangreichen Dokumentation: JavaDoc Viewer-Beispiel

Hier ist auch ein Bild:

Ein intelligenter, durchsuchbarer Javadoc-Betrachter:

Ich habe oft das Problem, in JavaDoc zu surfen. Ich suchte nach etwas wie Adnroid Doc Search Option. Endlich bekomme ich so etwas. Wenn Sie Firefox verwenden, ist die Lösung hier.

1. Installieren Sie das Plugin GreaseMonkey, dessen Webseite so angepasst wird, wie wir es sehen. (Wir müssen jede Java-Dokumentseite anpassen, damit wir nach dem Klassennamen suchen können.) Https://addons.mozilla.org/en-US/firefox/addon/greasemonkey/

2. Damit greasemonkey funktioniert, benötigen wir ein Benutzerskript zur Anpassung. Dies kann von greasemonkey automatisch heruntergeladen werden. Installieren Sie das Userscript aus dem JavaDoc- Suchrahmen oder der inkrementellen JavaDoc-Suche .

Das funktioniert gut für mich.