javadoc uses wrong URL for JDK 11 and 12

Description

Originally asked about in this ask.clojure.org question: https://ask.clojure.org/index.php/8422/clojure-javadoc-javadoc-fails-javadoc-classes-outside-module

The clojure.java.javadoc/javadoc function hard-codes the Java module name "java.base" in the URL it uses for JDK 11 and 12, so uses the wrong URL when creating a URL for any Java class outside of that Java module.

For example, if you evaluate:

(javadoc java.sql.Connection)

It tries to go to this non-existent URL: https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/sql/Connection.html

rather than the correct URL obtained by replacing the incorrect module name "java.base" in that URL with the correct one "java.sql".

Approach: Use reflection to obtain the class's module (for jdk classes), and then use that to properly form the javadoc url. Still continues to work for pre-module (jdk 8) classes as well.

Patch: clj-2354-v4.patch

Screened by: Alex Miller

Environment

None

Activity

Show:
Andy Fingerhut
September 5, 2019, 10:48 PM

The .contains check in clj-2534-v1.patch also prevents the code from calling a non-existent .getModule method when running on JDK 8. There are other ways to achieve that, of course.

Andy Fingerhut
September 6, 2019, 6:10 AM

I attached another patch clj-2534-v2.patch for consideration. It is identical to clj-2534-v1.patch except that it uses %s instead of {JAVA_MODULE_NAME} as the placeholder for where to put the module name, and format instead of .replace to make the substitution. It still uses a conditional check with .contains, but now with a comment explaining why.

Alex Miller
September 6, 2019, 2:46 PM

The new method should be private and you introduced reflection on the .contains call in that method - should type hint url.

Andy Fingerhut
September 6, 2019, 5:56 PM

The patch in clj-2534-v3.patch builds and passes tests on JDK 8 and JDK 11, and introduces no reflection warnings on JDK 11 in the modified javadoc.clj source file, confirmed using (set warn-on-reflection true) in my local copy (not part of the patch, only in local tests on my machine). There are reflection warnings when compiled on JDK 8 and (set! warn-on-reflection true) because .getModule and .getName methods do not exist on JDK 8, but note that those methods are never called when executing on JDK 8.

The new added function uses defn- to make it private.

Alex Miller
October 16, 2020, 8:32 PM

Added new patch with trivial updates to the version map for recent javadoc, retained attribution.

Completed

Assignee

Unassigned

Reporter

Andy Fingerhut

Labels

Approval

Ok

Patch

Code and Test

Fix versions

Affects versions

Priority

Minor
Configure