info and eldoc ops: also return :doc-fragments when available

Author: vemv

CHANGELOG.md

@@ -4,6 +4,9 @@
 
 ### Changes
 
+* `info` and `eldoc` ops: also return `:doc-fragments`, `:doc-first-sentence-fragments`, `:doc-first-sentence-fragments` attributes when available.
+  * These are explained in https://github.com/clojure-emacs/orchard/blob/v0.15.0/src-newer-jdks/orchard/java/parser_next.clj#L2-L20
+  * These typically are only available when running a modern JDK through enrich-classpath.
 * Bump `orchard` to [1.5.0](https://github.com/clojure-emacs/orchard/blob/v0.15.0/CHANGELOG.md#0150-2023-09-20).
 * Bump `compliment` to [0.4.2](https://github.com/alexander-yakushev/compliment/blob/f7d872d/CHANGELOG.md#042-2023-09-17).
 

Makefile

@@ -1,4 +1,4 @@
-.PHONY: test quick-test fast-test eastwood cljfmt install fast-install smoketest deploy clean detect_timeout lein-repl repl lint light-kondo
+.PHONY: test quick-test fast-test eastwood cljfmt install fast-install smoketest deploy clean detect_timeout lein-repl repl lint light-kondo docs
 .DEFAULT_GOAL := quick-test
 
 CLOJURE_VERSION ?= 1.11
@@ -126,3 +126,6 @@ lein-repl: .enrich-classpath-lein-repl
 	fi
 
 repl: lein-repl
+
+docs:
+	lein docs

README.md

@@ -92,6 +92,11 @@ PROJECT_VERSION=0.37.1 make fast-install
 # Runs clj-kondo, cljfmt and Eastwood (in that order, with fail-fast).
 # Please try to run this before pushing commits.
 make lint
+
+# Regenerates our user manual.
+# When you modify our middleware such that its schema changes, please reflect so in the `cider.nrepl` namespace
+# and run:
+make docs
 ```
 
 ## Releasing to Clojars

doc/modules/ROOT/pages/nrepl-api/ops.adoc

@@ -314,6 +314,9 @@ Optional parameters::
 {blank}
 
 Returns::
+* `:doc-block-tags-fragments` May be absent. Represent the 'param', 'returns' and 'throws' sections a Java doc comment. It's a vector of fragments, where fragment is a map with ``:type`` ('text' or 'html') and ``:content`` plain text or html markup, respectively
+* `:doc-first-sentence-fragments` May be absent. Represents the first sentence of a Java doc comment. It's a vector of fragments, where fragment is a map with ``:type`` ('text' or 'html') and ``:content`` plain text or html markup, respectively
+* `:doc-fragments` May be absent. Represents the body of a Java doc comment, including the first sentence and excluding any block tags. It's a vector of fragments, where fragment is a map with ``:type`` ('text' or 'html') and ``:content`` plain text or html markup, respectively
 * `:status` done
 
 
@@ -439,6 +442,9 @@ Optional parameters::
 {blank}
 
 Returns::
+* `:doc-block-tags-fragments` May be absent. Represent the 'param', 'returns' and 'throws' sections a Java doc comment. It's a vector of fragments, where fragment is a map with ``:type`` ('text' or 'html') and ``:content`` plain text or html markup, respectively
+* `:doc-first-sentence-fragments` May be absent. Represents the first sentence of a Java doc comment. It's a vector of fragments, where fragment is a map with ``:type`` ('text' or 'html') and ``:content`` plain text or html markup, respectively
+* `:doc-fragments` May be absent. Represents the body of a Java doc comment, including the first sentence and excluding any block tags. It's a vector of fragments, where fragment is a map with ``:type`` ('text' or 'html') and ``:content`` plain text or html markup, respectively
 * `:status` done
 
 

src/cider/nrepl.clj

@@ -205,19 +205,27 @@ Depending on the type of the return value of the evaluation this middleware may
               :optional wrap-print-optional-arguments
               :returns {"formatted-edn" "The formatted data."}}}})
 
+(def fragments-desc
+  "It's a vector of fragments, where fragment is a map with `:type` ('text' or 'html') and `:content` plain text or html markup, respectively")
+
+(def fragments-doc
+  {"doc-fragments"                (str "May be absent. Represents the body of a Java doc comment, including the first sentence and excluding any block tags. " fragments-desc)
+   "doc-first-sentence-fragments" (str "May be absent. Represents the first sentence of a Java doc comment. " fragments-desc)
+   "doc-block-tags-fragments"     (str "May be absent. Represent the 'param', 'returns' and 'throws' sections a Java doc comment. " fragments-desc)})
+
 (def-wrapper wrap-info cider.nrepl.middleware.info/handle-info
   (cljs/requires-piggieback
    {:requires #{#'session}
     :handles {"info"
               {:doc "Return a map of information about the specified symbol."
                :requires {"sym" "The symbol to lookup"
                           "ns" "The current namespace"}
-               :returns {"status" "done"}}
+               :returns (merge {"status" "done"} fragments-doc)}
               "eldoc"
               {:doc "Return a map of information about the specified symbol."
                :requires {"sym" "The symbol to lookup"
                           "ns" "The current namespace"}
-               :returns {"status" "done"}}
+               :returns (merge {"status" "done"} fragments-doc)}
               "eldoc-datomic-query"
               {:doc "Return a map containing the inputs of the datomic query."
                :requires {"sym" "The symbol to lookup"

src/cider/nrepl/middleware/info.clj

@@ -81,8 +81,11 @@
 
 (defn eldoc-reply
   [msg]
-  (if-let [info (info msg)]
-    (eldoc/eldoc info)
+  (if-let [{:keys [doc-first-sentence-fragments doc-fragments doc-block-tags-fragments] :as info} (info msg)]
+    (cond-> (eldoc/eldoc info)
+      (seq doc-fragments)                (assoc :doc-fragments doc-fragments)
+      (seq doc-first-sentence-fragments) (assoc :doc-first-sentence-fragments doc-first-sentence-fragments)
+      (seq doc-block-tags-fragments)     (assoc :doc-block-tags-fragments doc-block-tags-fragments))
     {:status :no-eldoc}))
 
 (defn eldoc-datomic-query-reply

test/clj/cider/nrepl/middleware/info_test.clj

@@ -1,19 +1,25 @@
 (ns cider.nrepl.middleware.info-test
   (:require
-   [clojure.data]
-   [clojure.test :refer :all]
-   [clojure.string :as str]
    [cider.nrepl.middleware.info :as info]
    [cider.nrepl.test-session :as session]
-   [cider.test-ns.first-test-ns :as test-ns])
+   [cider.test-ns.first-test-ns :as test-ns]
+   [clojure.data]
+   [clojure.java.io :as io]
+   [clojure.string :as str]
+   [clojure.test :refer :all])
   (:import
-   [cider.nrepl.test TestClass AnotherTestClass YetAnotherTest]
-   [org.apache.commons.lang3 SystemUtils]))
+   (cider.nrepl.test AnotherTestClass TestClass YetAnotherTest)
+   (org.apache.commons.lang3 SystemUtils)))
 
 (defprotocol FormatResponseTest
   (proto-foo [this])
   (proto-bar [this] "baz"))
 
+(def enriched-classpath?
+  "Is enrich-classpath (or something equivalent) augmenting the classpath?"
+  (boolean (or (io/resource "java/lang/Thread.java")
+               (io/resource "java.base/java/lang/Thread.java"))))
+
 (deftest format-response-test
   (is (re-find #"^(https?|file|jar|zip):" ; resolved either locally or online
                (-> (info/info {:class "java.lang.Object" :member "toString"})
@@ -32,7 +38,7 @@
   (is (nil? (info/format-response (info/info {:ns "cider.nrepl.middleware.info" :sym "notincanter.core"}))))
   ;; unfound nses should fall through
   (is (nil? (info/format-response (info/info {:ns "cider.nrepl.middleware.nonexistent-namespace" :sym "a-var"}))))
-  ;; protorol docstring
+  ;; protocol docstring
   (is (-> (info/format-response (info/info {:ns "cider.nrepl.middleware.info-test" :sym "proto-foo"}))
           (contains? "doc")
           not))
@@ -106,6 +112,19 @@
         (is (= (:doc response) "a macro for testing"))
         (is (nil? (:spec response)))))
 
+    (when enriched-classpath?
+      (testing "'fragments' attributes are returned"
+        (let [{:keys [doc-fragments doc-first-sentence-fragments doc-block-tags-fragments]
+               :as response}
+              (session/message {:op "info"
+                                :class "java.lang.Thread"
+                                :member "sleep"})]
+          (testing (pr-str response)
+            (doseq [f [doc-fragments doc-first-sentence-fragments doc-block-tags-fragments]]
+              (is (vector? f))
+              (is (map? (first f))))
+            (is (= #{"done"} (:status response)))))))
+
     (testing "get info of a java instance method with return value"
       (let [response (session/message {:op "info"
                                        :class "cider.nrepl.test.TestClass"
@@ -317,6 +336,17 @@
         (is (not (contains? response :ns)))
         (is (= (:type response) "function"))))
 
+    (when enriched-classpath?
+      (testing "Fragments for java interop method with single class"
+        (let [{:keys [doc-fragments doc-first-sentence-fragments doc-block-tags-fragments]
+               :as response}
+              (session/message {:op "eldoc" :member "sleep" :class "java.lang.Thread"})]
+          (testing (pr-str response)
+
+            (doseq [f [doc-fragments doc-first-sentence-fragments doc-block-tags-fragments]]
+              (is (vector? f))
+              (is (map? (first f))))))))
+
     (testing "java interop method with single class"
       (let [response (session/message {:op "eldoc" :sym ".startsWith" :ns "cider.nrepl.middleware.info-test"})]
         (is (= (:class response) ["java.lang.String"])