I would like to be able to programmatically convert Javadoc comments (such as those in the generated code of LWJGL) to other formats (such as Markdown). This would allow me to do things like automatically generating an idiomatic Clojure wrapper for LWJGL with human-readable docstrings.
I can pick the Javadoc comments out of a source file using JavaParser, but that's where I get stuck. The answers to these two Stack Overflow questions from 2011 and 2013 recommend using the Doclet API, but according to the answer to this question from 2015:
The classes in the
com.sun.tools.*packages should be treated as internal APIs. There are clear warnings in the Java documentation that say that you should not write code that against these APIs.
In Java 8, the header of the class that your code is trying to use says:
This is NOT part of any supported API. If you write code that depends on this, you do so at your own risk. This code and its internal interfaces are subject to change or deletion without notice.
(The bolding is in the original!)
It didn't say that in Java 7 (ouch!) Indeed there are versions of the Javadoc FAQ which seem to encourage people reuse the standard doclet classes. Unfortunately, Oracle have decided to close off these classes, and have also made some breaking API changes which reinforces this, whether or not that was the intention of the changes
A Google search for "Javadoc parser" didn't turn up anything but Doclet itself. Since Doclet is unsupported, it seems to me that the best way to solve my problem would be to write a Javadoc parsing library myself. However, it seems implausible to me that such a thing would not already exist. I am not an expert on Javadoc; perhaps there is no standard "Javadoc format" and the question of "how can I parse a Javadoc" is incorrect.
I would like a Java library that
- takes a Javadoc comment string (such as
"/** foo */") and returns some sort of parse tree
- does not depend on any internal parts of the JDK (such as
- is available through some public Maven repository (such as Central or Clojars)
- doesn't say "don't use this" in its documentation
Does a supported Javadoc parsing library exist, or should I write one myself?