clojure.java.javadoc/javadoc fails to show javadoc for JDK classes outside of java.base module on JDK 11

Question

When running Clojure on JDK 11, the clojure.java.javadoc/javadoc function fails to open a proper URL to the JDK classes outside of the java.base module.

As an example:
- (javadoc java.lang.String) opens https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html
- (javadoc java.sql.Connection) opens https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/sql/Connection.html which is incorrect because the module name should be java.sql, NOT java.base.
The proper URL should be https://docs.oracle.com/en/java/javase/11/docs/api/java.sql/java/sql/Connection.html

It is caused by the *core-java-api* definition in the clojure.java.javadoc namespace.

I'm wondering if there's a better way how to generically handle all standard JDK classes, not just those in the java.base module.

Note that initially this issue has been raised in the Emacs Cider project : https://github.com/clojure-emacs/cider/issues/2687

Answer 1

This fix has been released in 1.10.2-alpha3.

Answer 2

Given a class klass, you can in Clojure use Java interop to determine the name of the module it is inside of using the getModule method https://docs.oracle.com/javase/9/docs/api/java/lang/Class.html#getModule--

then getName on the resulting module: https://docs.oracle.com/javase/9/docs/api/java/lang/Module.html#getName--

e.g.

user=> (.getName (.getModule java.sql.Connection))
"java.sql"

It looks like such URLs started with JDK 11, not with JDK 9 when modules were introduced, so this should not be used on JDK's earlier than 11.

Comments

Yes, I've found that.
However, it doesn't change the fact that `clojure.java.javadoc/javadoc` is basically broken on JDK 11 for classes outside the java.base module.
Maybe it wasn't supposed to work them in the first place?

---

Sure, it is definitely the case that the built-in behavior of clojure.java.javadoc/javadoc doesn't go to the correct URL when using JDK 11 (and probably not JDK 12, either, although I haven't tried that).  It would be nice if a later Clojure release improved upon that.

I may find some time to create a patch for Clojure, but in the mean time, I wanted to share what I had learned, in case you wanted to take a crack at doing so.  Happy to walk you through steps for creating and testing a patch if you are interested.

Answer 3

Juraj, I was looking into creating a proposed patch for Clojure's javadoc to improve upon this situation, and realized that Clojure's javadoc also attempts to calculate correct URL's for java docs for other libraries outside of the ones included with Java.

Do you (or anyone reading this) have any idea whether this idea of including the module name in the URL is being taken up by other projects besides the core Java libraries?

For Java itself, the deciding factor for including the Java module name appears to be "JDK is 11 or later". I have confirmed that the JDK 12 docs follow this. JDK 13 docs do not have URLs on Oracle's web site yet to know what the plan is there.

Comments

I thought about it a bit more, and came up with one possible proposed change to Clojure that might be acceptable, but it has not gone through any review yet, so I have no idea if the Clojure core team has any interest in changing the behavior in javadoc at all, let alone in the particular way suggested in the patch.

https://clojure.atlassian.net/browse/CLJ-2534

---

Interesting solution with the `JAVA_MODULE_NAME` placeholder and thanks for the Jira ticket.
I added a note about possible NPE there.