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

Lesezeit: 9 Minuten

Benutzer-Avatar
ivan_ivanovich_ivanoff

Seien wir ehrlich: Sie müssen kein Designer sein, um diesen Standard zu sehen Javadoc sieht hässlich aus.

Es gibt einige Ressourcen im Web, die neu gestaltetes Javadoc anbieten. Aber das Standardverhalten stellt das Produkt dar und sollte möglichst 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, vorhandenes Javadoc auf benutzerfreundlichere Weise zu durchsuchen, als es ein Browser tun würde?
Ich denke an so etwas wie den Dokumentationsbrowser von Mono.

Theoretische Frage:

Weiß jemand, ob es Pläne gibt, Javadoc auf eine irgendwie standardisierte Weise weiterzuentwickeln?
BEARBEITEN: Ein nützlicher Link zum Wiki von Sun zu diesem Thema.

  • Ich würde mich freuen, wenn javadoc gültige HTML 4.01- oder XHTML-Seiten erzeugen würde.

    – akarnokd

    22. Juni 2009 um 11:02 Uhr

  • Welche Usability-Probleme haben Sie?

    – Bassnull

    22. Juni 2009 um 11:04 Uhr

  • Warum sollte jemand das ablehnen? Ich denke, es ist eine vernünftige Frage: +1

    -Daniel Sloof

    22. Juni 2009 um 11:06 Uhr

  • (X)HTML sollte nicht der einzige Weg für Javadoc sein. Der Browser ist ein sehr eingeschränktes Werkzeug für den Zugriff auf eine (lokale) Wissensdatenbank.

    – ivan_ivanovich_ivanoff

    22. Juni 2009 um 11:06 Uhr

  • Ich persönlich mag Javadoc. Es ist klar, prägnant und auf den Punkt gebracht. Die MSDN-Site hingegen …

    – samoz

    22. Juni 2009 um 11:14 Uhr

Ich habe eine erstellt Markdown (Java) Doclet die Quellkommentare in Markdown-formatiertem Text entgegennimmt und dieselben HTML-Javadocs erstellt.

Das neue Doclet nimmt auch eine gewisse Neugestaltung des Textes vor, aber der generierte HTML-Code wird in diesem Stadium nicht geändert.

Das geht in gewisser Weise, um die HTML-in-Java-Kommentarprobleme zu lösen, die wahrscheinlich das größte Usability-Problem mit dem aktuellen Javadoc sind.

Benutzer-Avatar
Ralf Edmund

Ich glaube nicht, dass die Konzepte von Javadoc veraltet sind. Soweit ich sehen kann, wurzeln diese Konzepte vor Jahren in einem Produkt namens doxygen, das immer noch für andere Sprachen verfügbar ist (dh Objective-C, wo es stark verwendet wird). Auch dies hat seine Vorgänger – werfen Sie einen Blick auf die Programmierumgebung, die von Donald Knuth verwendet wurde, um TeX zu erstellen (Literarisches Programmieren).

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

Außerdem kann die Darstellung der Dokumentation über ein vom JavaDoc-Tool unterstütztes Plugin-System an Ihre speziellen Bedürfnisse angepasst werden. Sie könnten (wie wir) ein Plug-in bereitstellen, das direkt in einer Datenbank veröffentlicht, auf die direkt über das Internet zugegriffen werden kann. Durch die Nutzung von Kollaborationen kann jeder zusätzliche Kommentare oder Erläuterungen zur Dokumentation abgeben, die möglicherweise ihren Weg zurück in die Originalquelle finden.

  • Bitte werfen Sie einen Blick auf ScalaDoc2 scala-lang.org/api/current und sagen Sie dann noch einmal, Javadoc ist nicht veraltet. 🙂 Obwohl ich zugeben muss, dass dies mehr oder weniger die gleichen Grundkonzepte sind, nur eine VIEL bessere Implementierung. Das Gleiche könnte man wahrscheinlich mit einer neuen Implementierung des Javadoc-Tools tun.

    – Hans-Peter Störr

    11. September 2013 um 15:15 Uhr


Javadoc ist das beste System zur automatischen Generierung von Quellcodedokumentationen, 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! Obwohl ich zustimme, dass ein kleines Facelifting angebracht sein könnte und besonders JDK mühsam zu durchsuchen ist, würde ich es nicht wagen, das Rad komplett neu zu erfinden, denn was wir derzeit haben, ist eine RESTful, einfach zu bedienende Lösung für ihren Zweck, die funktioniert einfach überall.

  • Nun, mit dem Problem, dass die Intra-Page-Links (z http://download.oracle.com/javase/6/docs/api/java/lang/String.html#String(byte[])) sind ungültig, da sie Klammern, eckige Klammern und andere unzulässige Zeichen verwenden. Dies führt dazu, dass sie in einigen Browsern brechen.

    – Joey

    15. Oktober 2010 um 11:37 Uhr


  • Übrigens, ein Update zu diesem Kommentar, ich denke heutzutage tatsächlich, dass scaladoc2 (siehe scala-lang.org/api/current/index.html) ist tatsächlich besser als Javadoc, obwohl hauptsächlich, weil es die guten Teile von Javadocs ausleiht und dann einige andere raffinierte Dinge hinzufügt.

    – Esko

    19. Januar 2011 um 19:24 Uhr

  • Ein weiteres Update, das Javadoc-System, wurde in JDK7 überarbeitet und sieht heutzutage ziemlich schick aus. Als Referenz siehe die offizielle API Javadoc unter download.oracle.com/javase/7/docs/api

    – Esko

    30. August 2011 um 15:09 Uhr

  • Ja, aber es ist SO HÄSSLICH!

    – Ziggy

    21. Januar 2014 um 20:14 Uhr

  • @Ziggy Machen Sie dann Ihr eigenes CSS oder verwenden Sie die oben genannte API, um eine völlig einzigartige Dokumentseite zu generieren? 😛

    – Esko

    22. Januar 2014 um 15:15 Uhr

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

Wir schlagen Verbesserungen für javadoc/doclet für JDK7 vor. Die Projekt-Wiki-Seite befindet sich unter
http://wikis.sun.com/display/Javadoc/Home. Als Teil 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 modifiziert, dass es gültiges HTML und WCAG 2.0-konform ist.

Da wird also definitiv noch gearbeitet, wenn auch etwas verspätet. Einer der größten Nachteile von Javadoc ist in meinen Augen jedoch die sehr enge Koppelung mit HTML. Viele Klassen haben Javadoc, das wörtliches HTML enthält und sich darauf verlässt, dass die Ausgabe auch HTML ist. Schade, aber das wird sich nicht ändern, denke ich. Dennoch bedeutet dies, dass es Entwicklern freisteht, alles, was sie wollen, in HTML einzufügen, das genauso gut ungültig, nicht wohlgeformt usw. sein könnte. Die Anpassung der Ausgabe des javadoc-Tools ist also nur ein Teil davon, der andere gewinnt. t und kann sich nicht ändern und bleibt somit bestehen.

Was das Durchsuchen der Dokumentation betrifft, so finde ich auch die HTML-Dokumentation etwas unhandlich. Normalerweise verwende ich die Javadoc-Ansicht in Eclipse. Es hat auch Nachteile (langsam und Sie können nicht wirklich suchen), aber für die meisten Dinge ist es Good Enough™.

Benutzer-Avatar
Joachim Sauer

Ich persönlich finde Javadoc immer noch sehr nützlich. Zumal es standardisiert ist. Ich kenne keinen größeren Dokumentationsstil, den ich einfacher zu navigieren finde (das mag sehr subjektiv sein, aber ich persönlich finde MSDN zum Beispiel schrecklich zu benutzen).

Für die Suche: Verwenden Sie die Javadoc-Suchrahmen, macht es die Verwendung von Javadoc aller Art viel einfacher. Es ist erhältlich als Benutzerskript für Firefox und als Google Chrome-Erweiterung.

  • Es sieht für mich so aus, als ob Javadoc Search Frame nur nach Paket- und Klassennamen im linken Frame sucht, was nützlich ist, aber nicht so nützlich wie eine Volltextsuche wäre.

    – Glenn Lawrence

    8. November 2013 um 0:23 Uhr


Benutzer-Avatar
Gerrie

Um Ihre praktische Frage zu beantworten, habe ich gegoogelt und Freunde gefragt und bin auf diese gekommen. Forrestdoc, Doclet und Doxygen.

Die zweite Frage, ich würde sagen, ja, es ist nicht sehr “Web-oh-twoeye”, aber zumindest funktioniert es garantiert in einer Offline-Umgebung und es ist klein genug, um es zusammen mit Ihrer API zu versenden. Ich verachte die Verwendung von Frames, aber dann funktioniert es ziemlich gut für Javadoc. Ich habe keine Pläne gesehen, das zu ändern. Eclipse bietet einige Unterstützung für Javadoc, was das Lesen, Interpretieren und Generieren betrifft.

  • Es sieht für mich so aus, als ob Javadoc Search Frame nur nach Paket- und Klassennamen im linken Frame sucht, was nützlich ist, aber nicht so nützlich wie eine Volltextsuche wäre.

    – Glenn Lawrence

    8. November 2013 um 0:23 Uhr


Benutzer-Avatar
Michael Borgwart

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ürdest du als “brauchbarer” bezeichnen? Ich persönlich würde mir auf jeden Fall eine Volltextsuche und einen Browser mit besserer Nutzung wünschen, und AJAX könnte dabei wahrscheinlich helfen.

Nun, das Schöne an JavaDoc ist, dass es das Gegenteil von veraltet ist – es ist beliebig erweiterbar. Warum gehst du nicht voran und schreibst a doclet das erzeugt die Art von API-Dokument, das Sie wollen?

Warum das bisher noch niemand getan hat (was anscheinend der Fall ist), bleibt jedem selbst überlassen – vielleicht fühlt sich niemand so sehr danach wie Sie.

  • 1) Es ist eine Tatsache, dass der Eindruck von Benutzerfreundlichkeit von gutem Design abhängt. 2) AJAX – für eine lokale file://-Ressource? 3) Ich bin mir sicher, dass niemand im C/C++-Ökosystem so stark auf konsistente Benennung steht wie ich, aber das macht die Notwendigkeit konsistenter Benennung nicht ungültig.

    – ivan_ivanovich_ivanoff

    22. Juni 2009 um 11:20 Uhr

  • 1) Was genau würden Sie dann als „gutes Design“ bezeichnen? Ich für meinen Teil denke, dass das reguläre JavaDoc gut gestaltet ist. 2) Wäre kein echtes AJAX, nehme ich an, aber eine ähnliche Funktionalität sollte eigentlich 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 nicht allzu schwierig wäre.

    – Michael Borgwardt

    22. Juni 2009 um 11:30 Uhr

  • 1) Standardteil: stark strukturierte Daten, kein HTML. Implementierungsteil: eine in Java geschriebene Desktop-App 😉 3) Ich denke, es könnten viele Freiwillige gefunden werden, um Javadoc zu verbessern, aber um es ernst zu nehmen, wäre ein JSR erforderlich. Für dieses Thema nicht realistisch zu erreichen.

    – ivan_ivanovich_ivanoff

    22. Juni 2009 um 11:38 Uhr

  • @ivan_ivanovich_ivanoff: Was denken Sie, welche stark strukturierten Daten benötigt werden? Und warum nicht ein Javadoc-Doclet schreiben, das dieses Format produziert? Und ich lehne die Idee einer Desktop-App absolut ab, weil sie Sie an die spezifische App bindet, um die Dokumentation anzuzeigen.

    – Mnementh

    22. Juni 2009 um 11:55 Uhr

1227820cookie-checkGibt es gute und moderne Alternativen zu Javadoc? [closed]

This website is using cookies to improve the user-friendliness. You agree by using the website further.

Privacy policy