5

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.

For example:

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

  1. takes a Javadoc comment string (such as "/** foo */") and returns some sort of parse tree
  2. does not depend on any internal parts of the JDK (such as tools.jar)
  3. is available through some public Maven repository (such as Central or Clojars)
  4. doesn't say "don't use this" in its documentation

Does a supported Javadoc parsing library exist, or should I write one myself?

Improve this question
10
  • The answer you quoted is incorrect. It confuses the sun.* packages, about which there is a well-known warning, with the com.sun.* packages, about which there isn't. It would be impossible to write a JNDI program without using com.sun.*, for example.
    – user207421
    Jul 17, 2016 at 3:20
  • According to this answer, tools.jar, which includes com.sun.javadoc.*, "can't be distributed". So how can I distribute an app that depends on com.sun.javadoc.*? Or is that not the package that I would need in order to parse Javadoc comments programmatically?
    – Sam Estep
    Jul 17, 2016 at 11:19
  • You can't. You have to rely on a JDK being installed at the target. But this is different question. And why would an application without a JDK need to process Java source code?
    – EJP
    Jul 17, 2016 at 12:23
  • Obviously the JavaParser contributors believe that processing Java source code without using the JDK is a perfectly reasonable thing to do. Also, Clojure doesn't require a JDK, so the use case I gave at the very beginning of my question is another example.
    – Sam Estep
    Jul 17, 2016 at 12:57
  • It isn't the same thing at all. They don't have a dependency on the JDK because you don't need a JDK to write a parser. You have a dependency on the JDK, no two ways about it. But again this is a new question and nothing to do with this answer.
    – EJP
    Jul 17, 2016 at 18:06

1 Answer 1

Reset to default
0

There is a doc2java project which supports this:

doc2java project

There's also a search engine which can host JavaDocs and make them searchable.

References

Improve this answer
9

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.