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 ec7cdd67..1faf27df 100644 --- a/src/orchard/java.clj +++ b/src/orchard/java.clj @@ -345,26 +345,36 @@ (first ms) {:candidates (zipmap (map :class ms) ms)}))))) +(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: + 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/"}) + (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]] (when (.startsWith classname prefix) (str url path)))) - @javadoc/*remote-javadocs*) + (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 (or (javadoc-base-urls misc/java-api-version) + (javadoc-base-urls 11)))))) path)) ;;; ## Initialization @@ -378,4 +388,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 fefaf52a..66dc00d7 100644 --- a/test/orchard/java_test.clj +++ b/test/orchard/java_test.clj @@ -232,6 +232,76 @@ (is (= (:javadoc (member-info 'java.util.Hashtable 'putAll)) "java.base/java/util/Hashtable.html#putAll(java.util.Map)"))))))))) +(deftest resolve-javadoc-path-test + (let [get-url (comp resolve-javadoc-path (partial apply javadoc-url))] + (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/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)"))))) + + (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]))))) + (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*)] (testing "Class resolution"