Java-Bibliothek zum Analysieren von Javadoc-Kommentaren

Ich möchte in der Lage sein, Javadoc - Kommentare (z. B. im generierten Code von LWJGL ) programmgesteuert in andere Formate (z. B. Markdown ) zu konvertieren. Dies würde es mir ermöglichen, Dinge wie das automatische Generieren eines idiomatischen Clojure -Wrappers für LWJGL mit menschenlesbaren Docstrings zu tun.

Ich kann die Javadoc-Kommentare mit JavaParser aus einer Quelldatei auswählen , aber hier bleibe ich hängen. Die Antworten auf diese beiden Stack Overflow-Fragen von 2011 und 2013 empfehlen die Verwendung der Doclet-API , aber gemäß der Antwort auf diese Frage von 2015:

Die Klassen in den com.sun.tools.*Paketen sollten als interne APIs behandelt werden. Es gibt klare Warnungen in der Java-Dokumentation, die besagen, dass Sie keinen Code schreiben sollten, der gegen diese APIs verstößt.

Zum Beispiel:

In Java 8 sagt der Header der Klasse, die Ihr Code zu verwenden versucht:

Dies ist NICHT Teil einer unterstützten API. Wenn Sie Code schreiben, der davon abhängt, tun Sie dies auf eigenes Risiko. Dieser Code und seine internen Schnittstellen können ohne Vorankündigung geändert oder gelöscht werden.

(Die Fettschrift ist im Original!)

Es wurde nicht gesagt, dass in Java 7 (autsch!) Tatsächlich gibt es Versionen der Javadoc-FAQ, die die Leute zu ermutigen scheinen, die Standard-Doclet-Klassen wiederzuverwenden. Leider hat Oracle beschlossen, diese Klassen zu schließen, und auch einige bahnbrechende API-Änderungen vorgenommen, die dies verstärken, unabhängig davon, ob dies die Absicht der Änderungen war oder nicht

Eine Google-Suche nach "Javadoc-Parser" ergab nichts anderes als Doclet selbst. Da Doclet nicht unterstützt wird, scheint es mir, dass der beste Weg zur Lösung meines Problems darin besteht, selbst eine Javadoc-Parsing-Bibliothek zu schreiben. Dass so etwas nicht schon existiert, erscheint mir jedoch unglaubwürdig. Ich bin kein Experte für Javadoc; Vielleicht gibt es kein Standard-"Javadoc-Format" und die Frage "Wie kann ich ein Javadoc parsen" ist falsch .

Ich hätte gerne eine Java-Bibliothek dafür

  1. nimmt eine Javadoc-Kommentarzeichenfolge (z. B. "/** foo */") und gibt eine Art Analysebaum zurück
  2. hängt nicht von internen Teilen des JDK ab (wie etwa tools.jar)
  3. ist über ein öffentliches Maven-Repository verfügbar (wie Central oder Clojars )
  4. sagt nicht "benutze das nicht" in seiner Dokumentation

Gibt es eine unterstützte Javadoc-Parsing-Bibliothek oder sollte ich selbst eine schreiben?

Die von Ihnen zitierte Antwort ist falsch. Es verwechselt die sun.*Pakete, vor denen es eine bekannte Warnung gibt, mit den com.sun.*Paketen, vor denen es keine gibt. Es wäre beispielsweise unmöglich, ein JNDI-Programm ohne die Verwendung von zu schreiben com.sun.*.
Gemäß dieser Antwort , tools.jar, die enthält com.sun.javadoc.*, "kann nicht verteilt werden". Wie kann ich also eine App verteilen, die von abhängt com.sun.javadoc.*? Oder ist das nicht das Paket, das ich benötigen würde, um Javadoc-Kommentare programmgesteuert zu analysieren?
Du kannst nicht. Sie müssen sich darauf verlassen, dass ein JDK auf dem Ziel installiert ist. Aber das ist eine andere Frage. Und warum sollte eine Anwendung ohne JDK Java-Quellcode verarbeiten müssen?
Offensichtlich glauben die JavaParser- Mitwirkenden, dass die Verarbeitung von Java-Quellcode ohne Verwendung des JDK eine absolut vernünftige Sache ist. Außerdem benötigt Clojure kein JDK , daher ist der Anwendungsfall, den ich ganz am Anfang meiner Frage angegeben habe, ein weiteres Beispiel.
Es ist überhaupt nicht dasselbe. Sie haben keine Abhängigkeit vom JDK, da Sie kein JDK benötigen, um einen Parser zu schreiben. Sie haben eine Abhängigkeit vom JDK, keine zwei Möglichkeiten. Aber auch dies ist eine neue Frage und hat nichts mit dieser Antwort zu tun.
Es hat alles mit dieser Antwort zu tun. Die Doclet-API ist nicht nur „KEIN Teil einer unterstützten API“ (oder vielleicht gerade deshalb), sondern auch nicht allgemein programmgesteuert zur Laufzeit verfügbar, da sie ein JDK erfordert. Es ist keine Lösung für das Problem, das ich in meiner Frage beschrieben habe.
Das könntest du mit viel Mühe selbst schreiben. Warum benutzt du nicht einfach Doclet? a) Es funktioniert ... jetzt . b) Wenn die APIs, die Sie von Doclet haben möchten, jemals verschwinden, können Sie die ältere Doclet-Quelle nehmen und sie als Ihre eigene behandeln, als ob Sie sie geschrieben hätten.
@IraBaxter Könnten Sie einen Link zu dem Teil der Doclet-Quelllizenz posten, der besagt, dass ich ihn als meinen behandeln darf?
OK, fairer Punkt. Mein Punkt ist, dass Sie wählen können, ob Sie jetzt einen Haufen Arbeit erledigen oder diese Arbeit einfach verschieben möchten. Das Schlimmste, was passiert, ist, dass Sie ein solches Tool schreiben müssen, wenn Doclet verschwindet; Das kann nicht schlimmer sein, als dieses Tool jetzt zu schreiben, mit dem Gewinn, dass Sie es vielleicht nie müssen. APIs halten viel länger, als irgendjemand zugeben wird.
@IraBaxter Das macht definitiv Sinn, aber dazu müsste ich die Doclet-API lernen, was ich nicht tun müsste, wenn ich jetzt nur die Bibliothek schreibe. Außerdem spricht es nicht die Tatsache an, dass alles, was ich schreibe, das die Doclet-API verwendet, schwieriger zu verteilen ist.

Antworten (1)

Es gibt ein doc2java-Projekt, das dies unterstützt:

doc2java-Projekt

Es gibt auch eine Suchmaschine, die JavaDocs hosten und durchsuchbar machen kann.

Verweise

Ist das nicht umgekehrt? Sieht so aus, als hätte OP den Java-Code und möchte nur die 'Javadoc'-Kommentare daraus haben? Ich denke, ein besseres Werkzeug wäre zB doxygen und die Ausgabe von XML-Ausgaben zur weiteren Verarbeitung.
@albert Ich bin gerade von einer Suchmaschine hierher gekommen und habe die Frage anhand des Titels beantwortet
Ich denke, geeignetere Antworten mit Google können erhalten werden, vielleicht so etwas wie: docs.oracle.com/javase/6/docs/technotes/guides/javadoc/doclet/… oder tomassetti.me/… oder stackoverflow.com/questions/24727110/ …
@Albert Danke. Hoffentlich antwortet der OP.
Ja, wie @albert sagte, das beantwortet die Frage nicht.
@SamEstep Hast du dir die Vorschläge angesehen, die ich gegeben habe (ich habe mich nicht eingehend damit befasst, daher bin ich mir nicht sicher, was sie in Bezug auf die Frage wert sind) oder hast du eine andere Lösung gefunden (wenn ja, füge sie bitte deiner hinzu Frage oder Post als Antwort, je nachdem, ob es sich um eine Problemumgehung oder eine gute Lösung handelt)
@albert habe ich; Doclet würde aus Gründen, die ich in der ursprünglichen Frage erwähnt habe, nicht funktionieren, und wie in diesem Artikel angegeben, kann JavaParser zwar die JavaDoc-Kommentare selbst extrahieren, sie jedoch nicht analysieren (und das relevante Problem, das am Ende des Artikels verlinkt ist, wurde geschlossen). Eine gute Lösung habe ich noch nicht gefunden.
@SamEstep Probieren Sie einfach Doxygen mit XML-Ausgabe aus (setzen Sie einfach EXTRACT_ALL auf YES und GENERATE_XML auf YES) und sehen Sie, was Sie im XML-Verzeichnis erhalten. Vielleicht können Sie dies weiter analysieren.
@albert Das ist eine gute Idee, danke; Ich hatte eine Weile keine Zeit, an diesem Projekt zu arbeiten, aber wenn ich darauf zurückkomme, werde ich es auf jeden Fall versuchen.
Java-Bibliothek zum Analysieren von Javadoc-Kommentaren
AntwortenHierDatenschutz-Bestimmungen1y, 0v