Prerelease edits

* Avoid naming clash with existing auto referred javadoc
* Add useful exception when using less than minimum java version
* Separate namespaces into impl and api

Author: JarrodCTaylor

README.md

@@ -1,4 +1,4 @@
-# java.javadocs
+# clojure.java.doc
 
 A Clojure library for accessing JDK javadocs in your REPL
 
@@ -7,8 +7,8 @@ A Clojure library for accessing JDK javadocs in your REPL
 ### deps.edn
 
 ```clojure
-{:deps {org.clojure/java.javadoc {:git/url "https://github.com/clojure/java.javadoc"
-                                  :git/sha "b98dfbc6360964ae5831ed21f4b794f05568e8d0"}}}
+{:deps {org.clojure/clojure.java.doc {:git/url "https://github.com/clojure/java.javadoc"
+                                      :git/sha "b98dfbc6360964ae5831ed21f4b794f05568e8d0"}}}
 ```
 
 ### In the REPL with add-libs
@@ -19,53 +19,53 @@ For usage without modifying your project deps:
 ;; This require is only necessary if not in user namespace
 (require '[clojure.repl.deps :refer [add-lib]])
 
-(add-lib 'org.clojure/java.javadoc)
+(add-lib 'org.clojure/clojure.java.doc)
 
-(require '[java-javadocs.core :refer [javadoc javadoc-data]])
+(require '[clojure.java.doc.api :refer [jdoc jdoc-data]])
 
 ;; Now you can use it
-(javadoc String)
+(jdoc String)
 ```
 
 ### From the Command Line
 
 Invoke directly from the command line, useful for piping into a .md file to display in your editor:
 
 ```bash
-clojure -Sdeps '{:deps {org.clojure/java.javadoc {:git/url "https://github.com/clojure/java.javadoc" :git/sha "b98dfbc6360964ae5831ed21f4b794f05568e8d0"}}}' \
-  -M -e "(require '[java-javadocs.core :refer [javadoc]]) (javadoc String)"
+clojure -Sdeps '{:deps {org.clojure/clojure.java.doc {:git/url "https://github.com/clojure/clojure.java.doc" :git/sha "b98dfbc6360964ae5831ed21f4b794f05568e8d0"}}}' \
+  -M -e "(require '[clojure.java.doc.api :refer [jdoc]]) (jdoc String)"
 ```
 
 ## Usage
 
 The core namespace provides two functions:
 
-### javadoc
+### jdoc
 
 Prints a markdown formatted version of the javadoc description:
 
 ```clojure
-(require '[java-javadocs.core :refer [javadoc javadoc-data]])
+(require '[clojure.java.doc.api :refer [jdoc jdoc-data]])
 
 ;; Print class description
-(javadoc String)
+(jdoc String)
 
 ;; Print all overloads of a method
-(javadoc String/valueOf)
+(jdoc String/valueOf)
 
 ;; Specify a specific overload using param-tags
-(javadoc ^[char/1] String/valueOf)
+(jdoc ^[char/1] String/valueOf)
 
 ;; Use _ to match any type:
-(javadoc ^[_ int int] String/.substring)
+(jdoc ^[_ int] String/.substring)
 ```
 
-### javadoc-md
+### jdoc-data
 
 Returns structured data instead of printing:
 
 ```clojure
-(javadoc-data String)
+(jdoc-data String)
 ;; => {:classname "java.lang.String"
 ;;     :class-description-html "..."
 ;;     :class-description-md "..."
@@ -75,7 +75,7 @@ Returns structured data instead of printing:
 ;;                :clojure-call "^[int] String/valueOf"}
 ;;               ...]}
 
-(javadoc-data ^[char/1] String/valueOf)
+(jdoc-data ^[char/1] String/valueOf)
 ;; => {:classname "java.lang.String"
 ;;     :class-description-html "..."
 ;;     :class-description-md "..."

src/clojure/java/doc/api.clj

@@ -0,0 +1,27 @@
+(ns clojure.java.doc.api
+  (:require
+    [clojure.java.doc.impl :refer [parse-javadoc print-javadoc]]))
+
+(defn javadoc-data-fn [s param-tags]
+  (parse-javadoc s param-tags))
+
+(defn javadoc-fn [s param-tags]
+  (print-javadoc (javadoc-data-fn s param-tags)))
+
+(defmacro jdoc-data
+  "a map containg javadoc data for a class or method
+   Examples:
+     (jdoc-data String)                   ; Get class data
+     (jdoc-data String/valueOf)           ; Get data for all valueOf overloads
+     (jdoc-data ^[char/1] String/valueOf) ; Get data for specific overload"
+  [class-or-method]
+  `(javadoc-data-fn ~(str class-or-method) '~(:param-tags (meta class-or-method))))
+
+(defmacro jdoc
+  "print javadoc for a class or method
+   Examples:
+     (jdoc String)                    ; Print class description
+     (jdoc String/valueOf)            ; Print all valueOf overloads
+     (jdoc ^[char/1] String/valueOf)  ; Print specific overload"
+  [class-or-method]
+  `(javadoc-fn ~(str class-or-method) '~(:param-tags (meta class-or-method))))

src/java_javadocs/core.clj renamed to src/clojure/java/doc/impl.clj

@@ -1,20 +1,30 @@
-(ns java-javadocs.core
+(ns clojure.java.doc.impl
   (:require
     [clojure.string :as str])
   (:import [com.vladsch.flexmark.html2md.converter FlexmarkHtmlConverter]
            [org.jsoup Jsoup]))
 
 (set! *warn-on-reflection* true)
 
-(defn javadoc-url [^String classname]
+(defn- check-java-version [^String version-str]
+  (let [version (Integer/parseInt version-str)
+        min-version 17]
+    (when (< version min-version)
+      (throw (ex-info
+               (str "Java " min-version " or higher is required. Current version: " version-str)
+               {:current-version version-str
+                :minimum-version min-version})))))
+
+(defn- javadoc-url [^String classname]
   (let [java-version (System/getProperty "java.specification.version")
+        _ (check-java-version java-version)
         classname (str/replace classname #"\$.*" "")
         klass (Class/forName classname)
         module-name (.getName (.getModule klass))
         url-path (.replace classname \. \/)]
     (str "https://docs.oracle.com/en/java/javase/" java-version "/docs/api/" module-name "/" url-path ".html")))
 
-(defn html-to-md [^String html]
+(defn- html-to-md [^String html]
   (.convert ^FlexmarkHtmlConverter (.build (FlexmarkHtmlConverter/builder)) html))
 
 (defn- resolve-class-name [class-part]
@@ -105,71 +115,47 @@
         (str "^[" (str/join " " clojure-types) "] " class-part separator method-name))
       (str class-part separator method-name))))
 
-  (defn parse-javadoc
-    "parse the javadoc HTML for a class or method into a data structure:
-    {:classname 'java.lang.String'
-     :class-description-html '...'
-     :class-description-md '...'
-     :methods [...]
-     :selected-method [{:signature 'valueOf(char[] data)'
-                        :description 'Returns the string representation...'
-                        :static? true
-                        :clojure-call '^[char/1] String/valueOf'
-                        :method-description-html '...'
-                        :method-description-md '...'}]}"
-    [s param-tags]
-    (let [[class-part method-part] (str/split s #"/\.?" 2)
-          class-name (resolve-class-name class-part)
-          doc (Jsoup/parse (slurp (javadoc-url class-name)))
-          class-desc-section (.selectFirst doc "section.class-description")
-          method-rows (.select doc "div.method-summary-table.col-second")
-          all-methods (vec (for [^org.jsoup.nodes.Element method-div method-rows]
-                             (let [desc-div ^org.jsoup.nodes.Element (.nextElementSibling method-div)
-                                   signature (.text (.select method-div "code"))
-                                   modifier-div ^org.jsoup.nodes.Element (.previousElementSibling method-div)
-                                   modifier-html (when modifier-div (.html modifier-div))
-                                   is-static? (and modifier-html (str/includes? modifier-html "static"))]
-                               {:signature signature
-                                :description (.text (.select desc-div ".block"))
-                                :static? is-static?
-                                :clojure-call (clojure-call-syntax class-part signature is-static?)})))
-          class-html (.outerHtml class-desc-section)
-          result {:classname class-name
-                  :class-description-html class-html
-                  :class-description-md (html-to-md class-html)
-                  :methods all-methods}]
-      (if method-part
-        (let [filtered (filter-methods all-methods method-part param-tags)]
-          (assoc result :selected-method
-                 (mapv #(get-method-detail doc %) filtered)))
-        result)))
-
-(defn javadoc-data-fn [s param-tags]
-  (parse-javadoc s param-tags))
-
-(defn- print-javadoc [{:keys [class-description-md selected-method]}]
+(defn parse-javadoc
+  "parse the javadoc HTML for a class or method into a data structure:
+  {:classname 'java.lang.String'
+   :class-description-html '...'
+   :class-description-md '...'
+   :methods [...]
+   :selected-method [{:signature 'valueOf(char[] data)'
+                      :description 'Returns the string representation...'
+                      :static? true
+                      :clojure-call '^[char/1] String/valueOf'
+                      :method-description-html '...'
+                      :method-description-md '...'}]}"
+  [s param-tags]
+  (let [[class-part method-part] (str/split s #"/\.?" 2)
+        class-name (resolve-class-name class-part)
+        doc (Jsoup/parse (slurp (javadoc-url class-name)))
+        class-desc-section (.selectFirst doc "section.class-description")
+        method-rows (.select doc "div.method-summary-table.col-second")
+        all-methods (vec (for [^org.jsoup.nodes.Element method-div method-rows]
+                           (let [desc-div ^org.jsoup.nodes.Element (.nextElementSibling method-div)
+                                 signature (.text (.select method-div "code"))
+                                 modifier-div ^org.jsoup.nodes.Element (.previousElementSibling method-div)
+                                 modifier-html (when modifier-div (.html modifier-div))
+                                 is-static? (and modifier-html (str/includes? modifier-html "static"))]
+                             {:signature signature
+                              :description (.text (.select desc-div ".block"))
+                              :static? is-static?
+                              :clojure-call (clojure-call-syntax class-part signature is-static?)})))
+        class-html (.outerHtml class-desc-section)
+        result {:classname class-name
+                :class-description-html class-html
+                :class-description-md (html-to-md class-html)
+                :methods all-methods}]
+    (if method-part
+      (let [filtered (filter-methods all-methods method-part param-tags)]
+        (assoc result :selected-method
+               (mapv #(get-method-detail doc %) filtered)))
+      result)))
+
+(defn print-javadoc [{:keys [class-description-md selected-method]}]
   (if selected-method
     (doseq [{:keys [method-description-md]} selected-method]
       (println method-description-md))
     (println class-description-md)))
-
-(defn javadoc-fn [s param-tags]
-  (print-javadoc (javadoc-data-fn s param-tags)))
-
-(defmacro javadoc-data
-  "a map containg javadoc data for a class or method
-   Examples:
-     (javadoc-data String)                   ; Get class data
-     (javadoc-data String/valueOf)           ; Get data for all valueOf overloads
-     (javadoc-data ^[char/1] String/valueOf) ; Get data for specific overload"
-  [class-or-method]
-  `(javadoc-data-fn ~(str class-or-method) '~(:param-tags (meta class-or-method))))
-
-(defmacro javadoc
-  "print javadoc for a class or method
-   Examples:
-     (javadoc String)                    ; Print class description
-     (javadoc String/valueOf)            ; Print all valueOf overloads
-     (javadoc ^[char/1] String/valueOf)  ; Print specific overload"
-  [class-or-method]
-  `(javadoc-fn ~(str class-or-method) '~(:param-tags (meta class-or-method))))