Add constructor support to jdoc, jdoc-data, and sigs

Author: JarrodCTaylor

README.md

@@ -94,6 +94,10 @@ Returns all the structured data instead of printing the description.
 ;; => {:classname "java.lang.String"
 ;;     :class-description-html "..."
 ;;     :class-description-md "..."
+;;     :constructors [{:signature "String()"
+;;                     :description "Initializes a newly created String..."
+;;                     :clojure-call "String/new"}
+;;                    ...]
 ;;     :methods [{:signature "valueOf(int i)"
 ;;                :description "Returns the string representation..."
 ;;                :static? true
@@ -105,6 +109,7 @@ Returns all the structured data instead of printing the description.
 ;; => {:classname "java.lang.String"
 ;;     :class-description-html "..."
 ;;     :class-description-md "..."
+;;     :constructors [...]
 ;;     :methods [...]
 ;;     :selected-method [{:signature "valueOf(char[] data)"
 ;;                        :description "Returns the string representation..."
@@ -113,6 +118,19 @@ Returns all the structured data instead of printing the description.
 ;;                        :clojure-call "^[char/1] String/valueOf"
 ;;                        :method-description-html "..."
 ;;                        :method-description-md "..."}]}
+
+(jdoc-data String/new)
+;; => {:classname "java.lang.String"
+;;     :class-description-html "..."
+;;     :class-description-md "..."
+;;     :constructors [...]
+;;     :methods [...]
+;;     :selected-constructor [{:signature "String()"
+;;                             :description "Initializes a newly created String..."
+;;                             :clojure-call "String/.new"
+;;                             :constructor-description-html "..."
+;;                             :constructor-description-md "..."}
+;;                            ...]}
 ```
 
 ## Requirements

src/clojure/java/doc/impl.clj

@@ -141,6 +141,16 @@
           :method-description-md (html-to-md method-html)))
       method)))
 
+(defn- get-constructor-detail [^org.jsoup.nodes.Document doc constructor]
+  (let [param-types (extract-params (:signature constructor))
+        detail-section (find-method-section doc "<init>" param-types)]
+    (if detail-section
+      (let [html (.outerHtml ^org.jsoup.nodes.Element detail-section)]
+        (assoc constructor
+          :constructor-description-html html
+          :constructor-description-md (html-to-md html)))
+      constructor)))
+
 (defn- expand-array-syntax
   "expands array syntax for matching javadoc format: String/2 -> String[][]"
   [type-str]
@@ -233,6 +243,11 @@
         (str "^[" (str/join " " clojure-types) "] " class-part separator method-name))
       (str class-part separator method-name))))
 
+(defn- clojure-constructor-call-syntax [class-part constructor-signature]
+  (let [param-types (extract-params constructor-signature)
+        prefix (when param-types (str "^[" (str/join " " (mapv compress-array-syntax param-types)) "] "))]
+    (str prefix class-part "/.new")))
+
 (defn parse-javadoc
   "Parse the javadoc HTML for a class or method into a data structure:
   {:classname 'java.lang.String'
@@ -263,35 +278,50 @@
                               :static? is-static?
                               :return-type (clojure-return-type modifier-text)
                               :clojure-call (clojure-call-syntax class-part signature is-static?)})))
+        constructor-rows (.select ^org.jsoup.nodes.Document doc "div.col-constructor-name")
+        all-constructors (vec (for [^org.jsoup.nodes.Element ctor-div constructor-rows]
+                                (let [desc-div ^org.jsoup.nodes.Element (.nextElementSibling ctor-div)
+                                      signature (.text (.select ctor-div "code"))]
+                                  {:signature signature
+                                   :description (.text (.select desc-div ".block"))
+                                   :clojure-call (clojure-constructor-call-syntax class-part signature)})))
         class-html (when class-desc-section (.outerHtml ^org.jsoup.nodes.Element class-desc-section))
         result {:classname class-name
                 :class-description-html class-html
                 :class-description-md (when class-html (html-to-md class-html))
-                :methods all-methods}]
-    (if method-part
-      (let [filtered        (filter-methods all-methods method-part param-tags)
-            declaring-class (when (empty? filtered)
-                              (find-declaring-class class-name method-part param-tags))]
-        (assoc result :selected-method
-               (cond
-                 (seq filtered) (mapv #(get-method-detail doc %) filtered)
-                 declaring-class (:selected-method (parse-javadoc (str declaring-class "/." method-part) param-tags))
-                 :else [])))
-      result)))
+                :methods all-methods
+                :constructors all-constructors}]
+    (cond
+      (nil? method-part) result
+      (= method-part "new") (let [filtered (if param-tags
+                                             (filterv #(params-match? (extract-params (:signature %)) param-tags) all-constructors)
+                                             all-constructors)]
+                              (assoc result :selected-constructor (mapv #(get-constructor-detail doc %) filtered)))
+      :else (let [filtered (filter-methods all-methods method-part param-tags)
+                  declaring-class (when (empty? filtered) (find-declaring-class class-name method-part param-tags))]
+              (assoc result :selected-method
+                     (cond
+                       (seq filtered) (mapv #(get-method-detail doc %) filtered)
+                       declaring-class (:selected-method (parse-javadoc (str declaring-class "/." method-part) param-tags))
+                       :else []))))))
 
-  (defn print-javadoc [{:keys [classname class-description-md selected-method]}]
+  (defn print-javadoc [{:keys [classname class-description-md selected-method selected-constructor]}]
     (let [condense-lines (fn [s] (str/replace s #"\n{3,}" "\n\n"))]
       (cond
+        selected-constructor (doseq [{:keys [constructor-description-md]} selected-constructor]
+                               (if constructor-description-md
+                                 (println (condense-lines constructor-description-md))
+                                 (println "No javadoc description available for this constructor.")))
         selected-method (doseq [{:keys [method-description-md]} selected-method]
                           (if method-description-md
                             (println (condense-lines method-description-md))
                             (println "No javadoc description available for this method.")))
         class-description-md (println (condense-lines class-description-md))
         :else (println (str "No javadoc description available for class: " classname)))))
 
-(defn print-signatures [{:keys [classname methods selected-method]}]
-  (let [methods-to-print (or selected-method methods)]
-    (if (seq methods-to-print)
-      (doseq [{:keys [clojure-call]} methods-to-print]
+(defn print-signatures [{:keys [classname methods constructors selected-method selected-constructor]}]
+  (let [items-to-print (or selected-method selected-constructor (concat constructors methods))]
+    (if (seq items-to-print)
+      (doseq [{:keys [clojure-call]} items-to-print]
         (println clojure-call))
       (println (str "No method signatures available for: " classname)))))

test/clojure/java/doc/impl_test.clj

@@ -444,6 +444,76 @@
   (testing "nonexistent method returns nil"
     (is (nil? (#'sut/find-declaring-class "java.lang.String" "totallyFakeMethod" nil)))))
 
+(deftest clojure-constructor-call-syntax-test
+
+  (testing "constructor with single parameter"
+    (is (= "^[Reader] PushbackReader/.new"
+           (#'sut/clojure-constructor-call-syntax "PushbackReader" "PushbackReader(Reader in)"))))
+
+  (testing "constructor with multiple parameters"
+    (is (= "^[Reader int] PushbackReader/.new"
+           (#'sut/clojure-constructor-call-syntax "PushbackReader" "PushbackReader(Reader in, int size)"))))
+
+  (testing "constructor with no parameters"
+    (is (= "StringBuilder/.new"
+           (#'sut/clojure-constructor-call-syntax "StringBuilder" "StringBuilder()"))))
+
+  (testing "constructor with array parameter"
+    (is (= "^[char/1] String/.new"
+           (#'sut/clojure-constructor-call-syntax "String" "String(char[] value)")))))
+
+(deftest get-constructor-detail-test
+
+  (testing "finds constructor detail by <init> section ID"
+    (let [html "<html><body>
+                <section id='&lt;init&gt;(java.io.Reader,int)'>
+                  <h3>PushbackReader</h3>
+                  <div class='member-signature'>
+                    <span>public PushbackReader(Reader in, int size)</span>
+                  </div>
+                  <div class='block'>Creates a new pushback reader with a pushback buffer of the given size.</div>
+                </section>
+                </body></html>"
+          doc (Jsoup/parse html)
+          constructor {:signature "PushbackReader(Reader in, int size)" :description "test"}
+          actual (#'sut/get-constructor-detail doc constructor)
+          expected-html "<section id=\"&lt;init&gt;(java.io.Reader,int)\">\n <h3>PushbackReader</h3>\n <div class=\"member-signature\">\n  <span>public PushbackReader(Reader in, int size)</span>\n </div>\n <div class=\"block\">\n  Creates a new pushback reader with a pushback buffer of the given size.\n </div>\n</section>"
+          expected-md "### PushbackReader {#<init>(java.io.Reader,int)}\n\npublic PushbackReader(Reader in, int size)  \nCreates a new pushback reader with a pushback buffer of the given size.\n"]
+      (is (= expected-html (:constructor-description-html actual)))
+      (is (= expected-md (:constructor-description-md actual)))
+      (is (= "PushbackReader(Reader in, int size)" (:signature actual)))))
+
+  (testing "returns original constructor when detail not found"
+    (let [html "<html><body>
+                <section id='&lt;init&gt;(java.io.Reader)'>
+                  <h3>PushbackReader</h3>
+                </section>
+                </body></html>"
+          doc (Jsoup/parse html)
+          constructor {:signature "PushbackReader(String s)" :description "test"}
+          actual (#'sut/get-constructor-detail doc constructor)]
+      (is (= constructor actual)))))
+
+(testing "finds constructor section with <init> ID"
+  (let [html "<html><body>
+        <section id='&lt;init&gt;(java.io.Reader)'>
+        <h3>PushbackReader</h3>
+        </section>
+        <section id='&lt;init&gt;(java.io.Reader,int)'>
+        <h3>PushbackReader</h3>
+        </section>
+        </body></html>"
+        doc (Jsoup/parse html)
+        section-1 (#'sut/find-method-section doc "<init>" ["Reader"])
+        section-2 (#'sut/find-method-section doc "<init>" ["Reader" "int"])]
+    (is (= "<init>(java.io.Reader)" (.attr section-1 "id")))
+    (is (= "<init>(java.io.Reader,int)" (.attr section-2 "id")))))
+
+(testing "parses <init> constructor IDs"
+  (is (= ["java.io.Reader" "int"] (#'sut/extract-id-params "<init>(java.io.Reader,int)" "<init>")))
+  (is (= ["java.io.Reader"] (#'sut/extract-id-params "<init>(java.io.Reader)" "<init>")))
+  (is (= [] (#'sut/extract-id-params "<init>()" "<init>"))))
+
   (testing "distinguishes between overloads with different param counts"
     (let [html "<html><body>
                 <section id='run(java.util.Map)'>