From 3b35d9eb1d066df1c456a82b05976f2a7b658dff Mon Sep 17 00:00:00 2001 From: dan sutton Date: Sun, 23 Feb 2020 10:52:16 -0600 Subject: [PATCH 1/6] Fix javadoc urls on java 11 the core-java-api url prefix used from clojure.java.javadoc includes the java.base module so we just strip that out and use the module as we had been doing --- src/orchard/java.clj | 4 ++- test/orchard/java_test.clj | 69 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 72 insertions(+), 1 deletion(-) diff --git a/src/orchard/java.clj b/src/orchard/java.clj index ec7cdd67..d941b952 100644 --- a/src/orchard/java.clj +++ b/src/orchard/java.clj @@ -363,7 +363,9 @@ (some (let [classname (.replaceAll path "/" ".")] (fn [[prefix url]] (when (.startsWith classname prefix) - (str url path)))) + (str (cond-> url + (= 11 misc/java-api-version) (.replaceFirst "/java.base" "")) + path)))) @javadoc/*remote-javadocs*) path)) diff --git a/test/orchard/java_test.clj b/test/orchard/java_test.clj index fefaf52a..dfbefa00 100644 --- a/test/orchard/java_test.clj +++ b/test/orchard/java_test.clj @@ -1,6 +1,7 @@ (ns orchard.java-test (:require [clojure.java.io :as io] + [clojure.java.javadoc :as clojure.javadoc] [clojure.test :refer :all] [dynapath.util :as dp] [orchard.java :refer :all] @@ -232,6 +233,74 @@ (is (= (:javadoc (member-info 'java.util.Hashtable 'putAll)) "java.base/java/util/Hashtable.html#putAll(java.util.Map)"))))))))) +(def javadoc-bases + "Copied from clojure.java.javadoc. These are the base urls for + javadocs from `clojure.java.javadoc/*core-java-api*`" + {8 "http://docs.oracle.com/javase/8/docs/api/" + 9 "http://docs.oracle.com/javase/9/docs/api/" + 10 "http://docs.oracle.com/javase/10/docs/api/" + 11 "https://docs.oracle.com/en/java/javase/11/docs/api/java.base/"}) + +(deftest resolve-javadoc-path-test + (let [get-url (comp resolve-javadoc-path (partial apply javadoc-url))] + (when (= 8 misc/java-api-version) + (testing "Java 8 javadocs resolve to the correct urls" + (with-bindings {#'clojure.javadoc/*core-java-api* (javadoc-bases 8)} + (with-redefs [misc/java-api-version 8 + cache (atom {})] + (are [class url] (= url (get-url class)) + ['java.lang.String] + "https://docs.oracle.com/javase/8/docs/api/java/lang/String.html" + + ['java.lang.String 'contains nil] + "https://docs.oracle.com/javase/8/docs/api/java/lang/String.html#contains" + + ['java.lang.String 'contains ['java.lang.CharSequence]] + "https://docs.oracle.com/javase/8/docs/api/java/lang/String.html#contains-java.lang.CharSequence-"))))) + + (when (>= misc/java-api-version 9) + (testing "Java 9 javadocs resolve to the correct urls" + (with-bindings {#'clojure.javadoc/*core-java-api* (javadoc-bases 9)} + (with-redefs [misc/java-api-version 9 + cache (atom {})] + (testing "java.base modules resolve correctly" + (are [class url] (= url (get-url class)) + ['java.lang.String] + "https://docs.oracle.com/javase/9/docs/api/java/lang/String.html" + + ['java.lang.String 'contains nil] + "https://docs.oracle.com/javase/9/docs/api/java/lang/String.html#contains" + + ['java.lang.String 'contains ['java.lang.CharSequence]] + "https://docs.oracle.com/javase/9/docs/api/java/lang/String.html#contains-java.lang.CharSequence-")))))) + + ;; these tests require resolving module names so should only run on 11 + (when (= 11 misc/java-api-version) + (testing "Java 11 javadocs resolve to the correct urls" + (with-redefs [misc/java-api-version 11 + cache (atom {})] + (testing "java.base modules resolve correctly" + (are [class url] (= url (get-url class)) + ['java.lang.String] + "https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html" + + ['java.lang.String 'contains nil] + "https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html#contains" + + ['java.lang.String 'contains ['java.lang.CharSequence]] + "https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html#contains(java.lang.CharSequence)")) + + (testing "non java.base modules also resolve correctly" + (are [class url] (= url (get-url class)) + ['java.net.http.HttpClient] + "https://docs.oracle.com/en/java/javase/11/docs/api/java.net.http/java/net/http/HttpClient.html" + + ['java.net.http.HttpClient 'newHttpClient nil] + "https://docs.oracle.com/en/java/javase/11/docs/api/java.net.http/java/net/http/HttpClient.html#newHttpClient" + + ['java.net.http.HttpRequest 'newBuilder ['java.net.URI]] + "https://docs.oracle.com/en/java/javase/11/docs/api/java.net.http/java/net/http/HttpRequest.html#newBuilder(java.net.URI)"))))))) + (deftest class-resolution-test (let [ns (ns-name *ns*)] (testing "Class resolution" From fa40ece897dab8624a792dd02bf9756ac68db924 Mon Sep 17 00:00:00 2001 From: dan sutton Date: Sun, 23 Feb 2020 14:27:02 -0600 Subject: [PATCH 2/6] Don't try to use clojure.java.javadoc, just copy info clojure.java.javadoc uses dynamic vars but stuffs them in a map so its effectively no longer dynamic. Further, clojure 1.8 didn't have javadoc url prefixes for jdk 11 so we just port over all the information it was trying to do but in a better manner. We could try to reuse the machinery in there but we would be updating 6 of 11 keys to whatever the proper api is so its easier to just copy them over. --- src/orchard/java.clj | 46 +++++++++++++++++++++++--------- test/orchard/java_test.clj | 54 +++++++++++++++----------------------- 2 files changed, 54 insertions(+), 46 deletions(-) diff --git a/src/orchard/java.clj b/src/orchard/java.clj index d941b952..d998c07d 100644 --- a/src/orchard/java.clj +++ b/src/orchard/java.clj @@ -345,28 +345,48 @@ (first ms) {:candidates (zipmap (map :class ms) ms)}))))) +(def backported-javadoc-bases + "Copied from clojure.java.javadoc. These are the base urls for + javadocs from `clojure.java.javadoc/*core-java-api*`. It is here for + two reasons: + 1. add java 13 to this list + 2. backport for older Clojures" + {8 "https://docs.oracle.com/javase/8/docs/api/" + 9 "https://docs.oracle.com/javase/9/docs/api/" + 10 "https://docs.oracle.com/javase/10/docs/api/" + 11 "https://docs.oracle.com/en/java/javase/11/docs/api/" + 12 "https://docs.oracle.com/en/java/javase/12/docs/api/" + 13 "https://docs.oracle.com/en/java/javase/13/docs/api/"}) + +(def remote-javadocs + (sorted-map + "com.google.common." "http://google.github.io/guava/releases/23.0/api/docs/" + "java." backported-javadoc-bases + "javax." backported-javadoc-bases + "org.ietf.jgss." backported-javadoc-bases + "org.omg." backported-javadoc-bases + "org.w3c.dom." backported-javadoc-bases + "org.xml.sax." backported-javadoc-bases + "org.apache.commons.codec." "http://commons.apache.org/proper/commons-codec/apidocs/" + "org.apache.commons.io." "http://commons.apache.org/proper/commons-io/javadocs/api-release/" + "org.apache.commons.lang." "http://commons.apache.org/proper/commons-lang/javadocs/api-2.6/" + "org.apache.commons.lang3." "http://commons.apache.org/proper/commons-lang/javadocs/api-release/")) + (defn resolve-javadoc-path "Resolve a relative javadoc path to a URL and return as a map. Prefer javadoc resources on the classpath; then use online javadoc content for core API classes. If no source is available, return the relative path as is." [^String path] (or (resource/resource-full-path path) - ;; [bug#308] `*remote-javadocs*` is outdated WRT Java - ;; 8, so we try our own thing first. - (when (re-find #"^(java|javax|jdk|org.omg|org.w3c.dom|org.xml.sax)/" path) - (apply str ["https://docs.oracle.com" - (if (>= misc/java-api-version 11) "/en/java/javase/" "/javase/") - misc/java-api-version - "/docs/api/" - path])) - ;; If that didn't work, _then_ we fallback on `*remote-javadocs*`. (some (let [classname (.replaceAll path "/" ".")] - (fn [[prefix url]] + (fn [[prefix url|version->url]] (when (.startsWith classname prefix) - (str (cond-> url - (= 11 misc/java-api-version) (.replaceFirst "/java.base" "")) + (str (if (string? url|version->url) + url|version->url + (get url|version->url misc/java-api-version + "https://docs.oracle.com/javase/8/docs/api/")) path)))) - @javadoc/*remote-javadocs*) + remote-javadocs) path)) ;;; ## Initialization diff --git a/test/orchard/java_test.clj b/test/orchard/java_test.clj index dfbefa00..339542ce 100644 --- a/test/orchard/java_test.clj +++ b/test/orchard/java_test.clj @@ -1,7 +1,6 @@ (ns orchard.java-test (:require [clojure.java.io :as io] - [clojure.java.javadoc :as clojure.javadoc] [clojure.test :refer :all] [dynapath.util :as dp] [orchard.java :refer :all] @@ -233,46 +232,35 @@ (is (= (:javadoc (member-info 'java.util.Hashtable 'putAll)) "java.base/java/util/Hashtable.html#putAll(java.util.Map)"))))))))) -(def javadoc-bases - "Copied from clojure.java.javadoc. These are the base urls for - javadocs from `clojure.java.javadoc/*core-java-api*`" - {8 "http://docs.oracle.com/javase/8/docs/api/" - 9 "http://docs.oracle.com/javase/9/docs/api/" - 10 "http://docs.oracle.com/javase/10/docs/api/" - 11 "https://docs.oracle.com/en/java/javase/11/docs/api/java.base/"}) - (deftest resolve-javadoc-path-test (let [get-url (comp resolve-javadoc-path (partial apply javadoc-url))] - (when (= 8 misc/java-api-version) - (testing "Java 8 javadocs resolve to the correct urls" - (with-bindings {#'clojure.javadoc/*core-java-api* (javadoc-bases 8)} - (with-redefs [misc/java-api-version 8 - cache (atom {})] + (testing "Java 8 javadocs resolve to the correct urls" + (with-redefs [misc/java-api-version 8 + cache (atom {})] + (are [class url] (= url (get-url class)) + ['java.lang.String] + "https://docs.oracle.com/javase/8/docs/api/java/lang/String.html" + + ['java.lang.String 'contains nil] + "https://docs.oracle.com/javase/8/docs/api/java/lang/String.html#contains" + + ['java.lang.String 'contains ['java.lang.CharSequence]] + "https://docs.oracle.com/javase/8/docs/api/java/lang/String.html#contains-java.lang.CharSequence-"))) + + (when (>= misc/java-api-version 9) + (testing "Java 9 javadocs resolve to the correct urls" + (with-redefs [misc/java-api-version 9 + cache (atom {})] + (testing "java.base modules resolve correctly" (are [class url] (= url (get-url class)) ['java.lang.String] - "https://docs.oracle.com/javase/8/docs/api/java/lang/String.html" + "https://docs.oracle.com/javase/9/docs/api/java/lang/String.html" ['java.lang.String 'contains nil] - "https://docs.oracle.com/javase/8/docs/api/java/lang/String.html#contains" + "https://docs.oracle.com/javase/9/docs/api/java/lang/String.html#contains" ['java.lang.String 'contains ['java.lang.CharSequence]] - "https://docs.oracle.com/javase/8/docs/api/java/lang/String.html#contains-java.lang.CharSequence-"))))) - - (when (>= misc/java-api-version 9) - (testing "Java 9 javadocs resolve to the correct urls" - (with-bindings {#'clojure.javadoc/*core-java-api* (javadoc-bases 9)} - (with-redefs [misc/java-api-version 9 - cache (atom {})] - (testing "java.base modules resolve correctly" - (are [class url] (= url (get-url class)) - ['java.lang.String] - "https://docs.oracle.com/javase/9/docs/api/java/lang/String.html" - - ['java.lang.String 'contains nil] - "https://docs.oracle.com/javase/9/docs/api/java/lang/String.html#contains" - - ['java.lang.String 'contains ['java.lang.CharSequence]] - "https://docs.oracle.com/javase/9/docs/api/java/lang/String.html#contains-java.lang.CharSequence-")))))) + "https://docs.oracle.com/javase/9/docs/api/java/lang/String.html#contains-java.lang.CharSequence-"))))) ;; these tests require resolving module names so should only run on 11 (when (= 11 misc/java-api-version) From 8c744804c89235387f014055deba40ea762884f9 Mon Sep 17 00:00:00 2001 From: dan sutton Date: Mon, 24 Feb 2020 08:15:19 -0600 Subject: [PATCH 3/6] Allow for user added javadoc sources In order to do so, need to use clojure.java.javadoc/*remove-javadocs* but we update it with a proper version of the javadoc root. Some issues are that clojure 1.8 has an entry for java 7 and for java 8 so running clojure 1.8 on java 11 can't use javadocs without this hack. Clojure 1.10.1 doesn't have a javadoc source for java 13 so this ensures a consistent presence across all versions. --- src/orchard/java.clj | 31 +++++++++---------------------- test/orchard/java_test.clj | 9 ++++++++- 2 files changed, 17 insertions(+), 23 deletions(-) diff --git a/src/orchard/java.clj b/src/orchard/java.clj index d998c07d..7e6d0244 100644 --- a/src/orchard/java.clj +++ b/src/orchard/java.clj @@ -358,20 +358,6 @@ 12 "https://docs.oracle.com/en/java/javase/12/docs/api/" 13 "https://docs.oracle.com/en/java/javase/13/docs/api/"}) -(def remote-javadocs - (sorted-map - "com.google.common." "http://google.github.io/guava/releases/23.0/api/docs/" - "java." backported-javadoc-bases - "javax." backported-javadoc-bases - "org.ietf.jgss." backported-javadoc-bases - "org.omg." backported-javadoc-bases - "org.w3c.dom." backported-javadoc-bases - "org.xml.sax." backported-javadoc-bases - "org.apache.commons.codec." "http://commons.apache.org/proper/commons-codec/apidocs/" - "org.apache.commons.io." "http://commons.apache.org/proper/commons-io/javadocs/api-release/" - "org.apache.commons.lang." "http://commons.apache.org/proper/commons-lang/javadocs/api-2.6/" - "org.apache.commons.lang3." "http://commons.apache.org/proper/commons-lang/javadocs/api-release/")) - (defn resolve-javadoc-path "Resolve a relative javadoc path to a URL and return as a map. Prefer javadoc resources on the classpath; then use online javadoc content for core API @@ -379,14 +365,15 @@ [^String path] (or (resource/resource-full-path path) (some (let [classname (.replaceAll path "/" ".")] - (fn [[prefix url|version->url]] + (fn [[prefix url]] (when (.startsWith classname prefix) - (str (if (string? url|version->url) - url|version->url - (get url|version->url misc/java-api-version - "https://docs.oracle.com/javase/8/docs/api/")) - path)))) - remote-javadocs) + (str url path)))) + (into @javadoc/*remote-javadocs* + ;; clojure 1.8 has no javadoc for anything beyond java + ;; 8. clojure 1.10.1 doesn't have 13. We just backport them + ;; regardless of clojure version + (zipmap ["java." "javax." "org.ietf.jgss." "org.omg." "org.w3c.dom." "org.xml.sax"] + (repeat (backported-javadoc-bases misc/java-api-version))))) path)) ;;; ## Initialization @@ -400,4 +387,4 @@ ;; TODO: Seems those were hardcoded here accidentally - we should ;; probably provide a simple API to register remote JavaDocs. (javadoc/add-remote-javadoc "com.amazonaws." "http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/") -(javadoc/add-remote-javadoc "org.apache.kafka." "https://kafka.apache.org/090/javadoc/index.html?") +(javadoc/add-remote-javadoc "org.apache.kafka." "https://kafka.apache.org/090/javadoc/") diff --git a/test/orchard/java_test.clj b/test/orchard/java_test.clj index 339542ce..b6a25eb8 100644 --- a/test/orchard/java_test.clj +++ b/test/orchard/java_test.clj @@ -287,7 +287,14 @@ "https://docs.oracle.com/en/java/javase/11/docs/api/java.net.http/java/net/http/HttpClient.html#newHttpClient" ['java.net.http.HttpRequest 'newBuilder ['java.net.URI]] - "https://docs.oracle.com/en/java/javase/11/docs/api/java.net.http/java/net/http/HttpRequest.html#newBuilder(java.net.URI)"))))))) + "https://docs.oracle.com/en/java/javase/11/docs/api/java.net.http/java/net/http/HttpRequest.html#newBuilder(java.net.URI)"))))) + + (testing "Allows for added javadocs" + (with-redefs [cache (atom {})] + (is (= "http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/lambda/AWSLambdaClient.html" + (get-url ['com.amazonaws.services.lambda.AWSLambdaClient]))) + (is (= "https://kafka.apache.org/090/javadoc/org/apache/kafka/clients/consumer/ConsumerConfig.html" + (get-url '[org.apache.kafka.clients.consumer.ConsumerConfig]))))))) (deftest class-resolution-test (let [ns (ns-name *ns*)] From 77c50cf008d99ebb0ff2b9116681656ca8200467 Mon Sep 17 00:00:00 2001 From: dan sutton Date: Mon, 24 Feb 2020 08:32:43 -0600 Subject: [PATCH 4/6] Fallback to java 11 for javadocs --- src/orchard/java.clj | 3 ++- test/orchard/java_test.clj | 7 ++++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/src/orchard/java.clj b/src/orchard/java.clj index 7e6d0244..0df22525 100644 --- a/src/orchard/java.clj +++ b/src/orchard/java.clj @@ -373,7 +373,8 @@ ;; 8. clojure 1.10.1 doesn't have 13. We just backport them ;; regardless of clojure version (zipmap ["java." "javax." "org.ietf.jgss." "org.omg." "org.w3c.dom." "org.xml.sax"] - (repeat (backported-javadoc-bases misc/java-api-version))))) + (repeat (or (backported-javadoc-bases misc/java-api-version) + (backported-javadoc-bases 11)))))) path)) ;;; ## Initialization diff --git a/test/orchard/java_test.clj b/test/orchard/java_test.clj index b6a25eb8..80a29a18 100644 --- a/test/orchard/java_test.clj +++ b/test/orchard/java_test.clj @@ -294,7 +294,12 @@ (is (= "http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/lambda/AWSLambdaClient.html" (get-url ['com.amazonaws.services.lambda.AWSLambdaClient]))) (is (= "https://kafka.apache.org/090/javadoc/org/apache/kafka/clients/consumer/ConsumerConfig.html" - (get-url '[org.apache.kafka.clients.consumer.ConsumerConfig]))))))) + (get-url '[org.apache.kafka.clients.consumer.ConsumerConfig]))))) + (testing "Unrecognized java version doesn't blank out the javadocs" + (with-redefs [misc/java-api-version 12345 + cache (atom {})] + (is (= "https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html" + (get-url ['java.lang.String]))))))) (deftest class-resolution-test (let [ns (ns-name *ns*)] From 40872f8a00b304d85ffd00be505af58bf29768ae Mon Sep 17 00:00:00 2001 From: dan sutton Date: Tue, 25 Feb 2020 08:21:07 -0600 Subject: [PATCH 5/6] Only run unrecognized java version test on java 11 If we have an unrecognized java version, presumably it is higher than 11. It should have a notion of module name like 11 and 13. Running this test on 8 breaks the test because there is no module name so that part is missing from the slug. Seems the unrecognized versions will most likely follow this path so we fallback to java 11 javadocs with a module name rather than java 8 without them. --- test/orchard/java_test.clj | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/test/orchard/java_test.clj b/test/orchard/java_test.clj index 80a29a18..66dc00d7 100644 --- a/test/orchard/java_test.clj +++ b/test/orchard/java_test.clj @@ -295,11 +295,12 @@ (get-url ['com.amazonaws.services.lambda.AWSLambdaClient]))) (is (= "https://kafka.apache.org/090/javadoc/org/apache/kafka/clients/consumer/ConsumerConfig.html" (get-url '[org.apache.kafka.clients.consumer.ConsumerConfig]))))) - (testing "Unrecognized java version doesn't blank out the javadocs" - (with-redefs [misc/java-api-version 12345 - cache (atom {})] - (is (= "https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html" - (get-url ['java.lang.String]))))))) + (when (>= misc/java-api-version 11) + (testing "Unrecognized java version doesn't blank out the javadocs" + (with-redefs [misc/java-api-version 12345 + cache (atom {})] + (is (= "https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html" + (get-url ['java.lang.String])))))))) (deftest class-resolution-test (let [ns (ns-name *ns*)] From 50ec3aadd27ae903d5e00665e51d01cde389cece Mon Sep 17 00:00:00 2001 From: dan sutton Date: Sat, 29 Feb 2020 10:14:13 -0600 Subject: [PATCH 6/6] Rename javadoc-base-urls and add changelog --- CHANGELOG.md | 1 + src/orchard/java.clj | 6 +++--- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1d1aad7f..ba96680a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ ### Bugs fixed * [#83](https://github.com/clojure-emacs/orchard/pull/83): Ignore non file URLs when checking for directory or file extensions. +* [#84](https://github.com/clojure-emacs/orchard/pull/84): Fix javadoc urls ## 0.5.6 (2020-02-14) diff --git a/src/orchard/java.clj b/src/orchard/java.clj index 0df22525..1faf27df 100644 --- a/src/orchard/java.clj +++ b/src/orchard/java.clj @@ -345,7 +345,7 @@ (first ms) {:candidates (zipmap (map :class ms) ms)}))))) -(def backported-javadoc-bases +(def javadoc-base-urls "Copied from clojure.java.javadoc. These are the base urls for javadocs from `clojure.java.javadoc/*core-java-api*`. It is here for two reasons: @@ -373,8 +373,8 @@ ;; 8. clojure 1.10.1 doesn't have 13. We just backport them ;; regardless of clojure version (zipmap ["java." "javax." "org.ietf.jgss." "org.omg." "org.w3c.dom." "org.xml.sax"] - (repeat (or (backported-javadoc-bases misc/java-api-version) - (backported-javadoc-bases 11)))))) + (repeat (or (javadoc-base-urls misc/java-api-version) + (javadoc-base-urls 11)))))) path)) ;;; ## Initialization