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

80

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 .

ivan_ivanovich_ivanoff
quelle
4
Ich würde mich freuen, wenn javadoc gültige HTML 4.01- oder XHTML-Seiten generieren würde.
Akarnokd
2
Welche Usabilitätsprobleme haben Sie?
Basszero
15
Warum sollte jemand dies ablehnen? Ich denke, es ist eine vernünftige Frage: +1
Daniel Sloof
2
(X) HTML sollte nicht der einzige Weg für Javadoc sein. Der Browser ist ein sehr begrenztes Tool für den Zugriff auf eine (lokale) Wissensdatenbank.
ivan_ivanovich_ivanoff
14
Ich persönlich mag Javadoc. Es ist klar, prägnant und auf den Punkt. Die MSDN-Seite auf der anderen Seite ...
Samoz

Antworten:

42

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.

Richard Nichols
quelle
21

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.

Ralf Edmund
quelle
1
Bitte schauen Sie sich ScalaDoc2 scala-lang.org/api/current an und sagen Sie dann noch einmal, dass Javadoc nicht veraltet ist. :-) Obwohl ich zugebe, dass das mehr oder weniger die gleichen Grundkonzepte sind, nur eine viel bessere Implementierung. Das könnte man wahrscheinlich auch mit einer neuen Implementierung des Javadoc-Tools tun.
Hans-Peter Störr
13

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.

Esko
quelle
1
Nun, mit dem Problem, dass die Intra-Page-Links (z. B. http://download.oracle.com/javase/6/docs/api/java/lang/String.html#String(byte[])) ungültig sind, da sie Klammern, Klammern und andere Zeichen verwenden, die nicht zulässig sind. Dies führt dazu, dass einige Browser beschädigt werden.
Joey
1
Übrigens, ein Update zu diesem Kommentar, ich denke heutzutage tatsächlich, dass scaladoc2 (siehe scala-lang.org/api/current/index.html ) tatsächlich besser ist als javadoc, obwohl es hauptsächlich die guten Teile von javadocs ausleiht und dann hinzufügt einige andere raffinierte Dinge drin.
Esko
2
Ein weiteres Update, das Javadoc-System, wurde in JDK7 überarbeitet und sieht heutzutage ziemlich schick aus. Als Referenz können Sie die offizielle API javadoc unter download.oracle.com/javase/7/docs/api
Esko vom
Ja, aber es ist so hässlich!
Ziggy
@Ziggy Erstellen Sie dann Ihr eigenes CSS oder verwenden Sie die oben genannte API, um eine vollständig eindeutige Dokumentseite zu erstellen? : P
Esko
11

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.

Joey
quelle
GROSSARTIGE NEUIGKEITEN !!! DANKE !!! Ich werde jetzt meine Frage bearbeiten, um diesen nützlichen Link bereitzustellen.
ivan_ivanovich_ivanoff
@ivan_ivanovich_ivanoff, vielleicht könnten Sie Ihre Bedenken auch gegenüber dem Sun-Team äußern. Klingt so, als ob sie dich glücklich machen können, es wird uns allen zugute kommen.
Thorbjørn Ravn Andersen
5

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 .

Joachim Sauer
quelle
1
Für mich sieht es so aus, als würde der Javadoc-Suchrahmen nur nach Paket- und Klassennamen im linken Rahmen suchen, was nützlich ist, aber nicht so nützlich wie eine Volltextsuche.
Glenn Lawrence
4

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.

Gerrie
quelle
3

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.

Michael Borgwardt
quelle
1
1) Es ist eine Tatsache, dass der Eindruck der Benutzer von Benutzerfreundlichkeit von gutem Design abhängt. 2) AJAX - für eine lokale Datei: // Ressource? 3) Ich bin sicher, niemand im C / C ++ - Ökosystem hat eine so starke Meinung zu konsistenter Benennung wie ich, aber dies macht die Notwendigkeit einer konsistenten Benennung nicht ungültig.
ivan_ivanovich_ivanoff
2
1) Was genau würdest du dann als "gutes Design" bezeichnen? Zum einen denke ich, dass das reguläre JavaDoc gut gestaltet ist. 2) Wäre kein echtes AJAX, nehme ich an, aber ähnliche Funktionen sollten tatsächlich möglich sein. 3) Trotzdem sieht es so aus, als ob das aktuelle JavaDoc für die meisten Leute gut genug ist, dass sich bisher niemand die Mühe gemacht hat, ein besseres zu erstellen - was gar nicht so schwierig wäre.
Michael Borgwardt
1
1) Standardteil: stark strukturierte Daten, kein HTML. Implementierungsteil: eine in Java geschriebene Desktop-App;) 3) Ich denke, es konnten viele Freiwillige gefunden werden, um Javadoc zu verbessern, aber um es ernst zu nehmen, wäre ein JSR erforderlich. Nicht realistisch für dieses Thema zu erreichen.
ivan_ivanovich_ivanoff
@ivan_ivanovich_ivanoff: Was denkst du, welche stark strukturierten Daten benötigt werden? Und warum nicht ein Javadoc-Doclet schreiben, das dieses Format erzeugt? Und ich lehne die Idee einer Desktop-App absolut ab, weil sie Sie an die spezifische App bindet, um die Dokumentation anzuzeigen.
Mnementh
2

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.

Nat
quelle
2

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).

JeeBee
quelle
2

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 .

pmf
quelle
1

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: Geben Sie hier die Bildbeschreibung ein

pgfearo
quelle
0

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.

Karim
quelle