Doc updates

Author: JarrodCTaylor

README.md

@@ -1,14 +1,14 @@
-# clojure.java.doc
+# java.doc
 
-A Clojure library for accessing JDK javadocs in your REPL
+A Clojure library for accessing Javadocs in your REPL
 
 ## Installation
 
 ### deps.edn
 
 ```clojure
-{:deps {org.clojure/clojure.java.doc {:git/url "https://github.com/clojure/java.javadoc"
-                                      :git/sha "54ada3611e1372ad30b03112f5b7c16ea8f47bbc"}}}
+{:deps {org.clojure/java.doc {:git/url "https://github.com/clojure/java.javadoc"
+                              :git/sha "54ada3611e1372ad30b03112f5b7c16ea8f47bbc"}}}
 ```
 
 ### In the REPL with add-libs
@@ -19,9 +19,9 @@ 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 'io.github.clojure/clojure.java.doc {:git/sha "54ada3611e1372ad30b03112f5b7c16ea8f47bbc"})
+(add-lib 'io.github.clojure/java.doc {:git/sha "54ada3611e1372ad30b03112f5b7c16ea8f47bbc"})
 
-(require '[clojure.java.doc.api :refer [jdoc jdoc-data]])
+(require '[clojure.java.doc.api :refer [jdoc jdoc-data sigs]])
 
 ;; Now you can use it
 (jdoc String)
@@ -32,7 +32,7 @@ For usage without modifying your project deps:
 Invoke directly from the command line, useful for piping into a .md file to display in your editor:
 
 ```bash
-clojure -Sdeps '{:deps {org.clojure/clojure.java.doc {:git/url "https://github.com/clojure/clojure.java.doc" :git/sha "54ada3611e1372ad30b03112f5b7c16ea8f47bbc"}}}' \
+clojure -Sdeps '{:deps {org.clojure/java.doc {:git/url "https://github.com/clojure/java.doc" :git/sha "54ada3611e1372ad30b03112f5b7c16ea8f47bbc"}}}' \
   -M -e "(require '[clojure.java.doc.api :refer [jdoc]]) (jdoc String)"
 ```
 
@@ -42,10 +42,10 @@ The core namespace provides three functions:
 
 ### jdoc
 
-Prints a markdown formatted version of the javadoc description:
+Print Javadoc HTML as Markdown for a class or qualified method (with optional param-tags).
 
 ```clojure
-(require '[clojure.java.doc.api :refer [jdoc jdoc-data]])
+(require '[clojure.java.doc.api :refer [jdoc jdoc-data sigs]])
 
 ;; Print class description
 (jdoc String)
@@ -62,7 +62,7 @@ Prints a markdown formatted version of the javadoc description:
 
 ### sigs
 
-Prints the method signatures in param tags form:
+Print method signatures in qualified method syntax with param tags.
 
 ```clojure
 (sigs String/valueOf)
@@ -79,7 +79,7 @@ Prints the method signatures in param tags form:
 
 ### jdoc-data
 
-Returns structured data instead of printing:
+Returns all the structured data instead of printing the description.
 
 ```clojure
 (jdoc-data String)
@@ -108,7 +108,6 @@ Returns structured data instead of printing:
 ## Requirements
 
 - Java 17+
-- Internet required to fetch html javadocs from docs.oracle.com
 
 ## Copyright and License
 

deps.edn

@@ -1,6 +1,6 @@
 {:paths ["src"]
  :deps {org.clojure/clojure {:mvn/version "1.12.3"}
-        org.clojure/tools.deps {:mvn/version "0.20.1440"}
+        org.clojure/tools.deps {:mvn/version "0.26.1553"}
         com.vladsch.flexmark/flexmark-html2md-converter {:mvn/version "0.64.8"}
         org.jsoup/jsoup {:mvn/version "1.18.1"}}
  :aliases {:dev {:extra-paths ["test"]

src/clojure/java/doc/api.clj

@@ -9,7 +9,8 @@
   (print-javadoc (javadoc-data-fn s param-tags)))
 
 (defmacro jdoc-data
-  "a map containg javadoc data for a class or method
+  "Returns 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
@@ -18,7 +19,8 @@
   `(javadoc-data-fn ~(str class-or-method) '~(:param-tags (meta class-or-method))))
 
 (defmacro jdoc
-  "print javadoc for a class or method
+  "Print the javadoc html as markdown for a class or qualified method (with optional param-tags).
+
    Examples:
      (jdoc String)                    ; Print class description
      (jdoc String/valueOf)            ; Print all valueOf overloads
@@ -30,7 +32,8 @@
   (print-signatures (javadoc-data-fn s param-tags)))
 
 (defmacro sigs
-  "print method signatures in qualified method / param tags form
+  "Print method signatures in qualified method syntax with param tags.
+
    Examples:
      (sigs String/valueOf)  ; Print all valueOf signatures"
   [class-or-method]

src/clojure/java/doc/impl.clj

@@ -157,7 +157,7 @@
       (str class-part separator method-name))))
 
 (defn parse-javadoc
-  "parse the javadoc HTML for a class or method into a data structure:
+  "Parse the javadoc HTML for a class or method into a data structure:
   {:classname 'java.lang.String'
    :class-description-html '...'
    :class-description-md '...'