add support for javadoc visualisation in as flare

[behrica]

I propose to add support to Calva directly for a snippet which show "javadoc" for "current selection".
an example could be:

{:name "jdoc"
   :key "j"
   :snippet 
   (do
     (defmacro to-class-instance-form [form]
       ;;; their are probaly more cases
       (cond (symbol? form) (.getName (class (eval form)))
             :else
             (let [f (first form)]
               (if (.contains (str f)  ".")
                 (str  (.getName (class (eval (second form)))) "/" f)
                 (let [splits (str/split (str f) (re-pattern "/"))
                       class-name (.getName  (eval (symbol (first splits))))]
                   (format "%s/%s" class-name (second splits)))))))
     
     (add-lib 'io.github.clojure/java.doc {:git/tag "v0.1.2" :git/sha "fc518b1"})
     (require '[clojure.java.doc.api])
     (let [jdoc-info (clojure.java.doc.api/javadoc-data-fn (to-class-instance-form $enclosing-form) nil)]
       (tagged-literal 'flare/html {:html (format "%s"
                                                  ;(:class-description-html jdoc-info)
                                                  (str/join "\n"
                                                            (map
                                                             (fn [method-doc] (:method-description-html method-doc))
                                                             (-> jdoc-info :selected-method)))),
                                    :key "javadoc"
                                    :title "javadoc"})))
   
   }
  

[behrica]

Ideally this should even be rendered in "mouse hoover".
This does work for some java classes know.

The clojure.java.doc.api libray allows this for arbitrary Java classes, at least if javadoc is on Maven.
(but it does network calls doing so ...)

[behrica]

I thought about this a bit, and I think now that maybe Calva itself should not have this.
Calva relies for lots of things rightly on nrepl / orchard, as well for "docu lookup".

So maybe we should leave it this way, and wait that nrepl / orchard improves its "javadoc support".
I nevertheless think that Calva does not make full use of "javadoc" lookup as present in nrepl / orchard.
See here:
https://docs.cider.mx/cider/usage/working_with_documentation.html#looking-up-documentation

[behrica]

I searched a bit and saw that the "wrap-info" nrepl middle-ware returns javadoc, not sure if always:
https://github.com/clojure-emacs/cider-nrepl/blob/ec3e523d215dcae2183d20b6994eec7276751133/src/cider/nrepl/middleware/info.clj#L60

which calls into:

https://github.com/clojure-emacs/orchard/blob/3a311777307c639407903804f5904c0528344be1/src/orchard/info.clj#L189

which "currently" (I think) relies on "local jars", while the new "jdoc" would "download these jars".

Cider has lately announced a re-work of its javadoc support, but this pre-dates jdoc, current docu:
https://github.com/clojure-emacs/orchard/blob/3a311777307c639407903804f5904c0528344be1/src/orchard/info.clj#L189

[behrica]

So I think that this issue might better be split in 2 different ones:

1. documenting the above snippet as "example" on Calva docu site, if you see it is general useful
2. checking and ev. fixing if Calva currently uses the javadoc support as alreday provided by nrepl

I think that 1) is a more complete javadoc support then Calva has "today" , but the "real fix" of this is maybe better started from 2) and "see" what nrepl does and "might change" , now that clojure.java.doc is released.

see here as well for some questions and answers:
https://ask.clojure.org/index.php/14734/can-doc-and-jdoc-refactored-common-protocol-while-still-early
https://github.com/clojure/java.doc

[behrica]

The "docu" of this could be similar to:
https://calva.io/clj-java-decompiler/

Of course we needed to explain that there is "calva build-in javadoc support" already (as popup), which is "less complete", then what the "custom snippet" can do.
And its true, that I never understood, if I could "do anything" to make the Calva-build in "javadoc" support work in more cases (like me downloading some "source" jars somewhere)

we don't document this "existing javadoc support", neither, I think.
It seem to work for "JDK classes" out-of-the box in Calva, but not for more java classes / methods.
(but probbaly depending if "src.zip" or other "source jars" are found somehwhere on disk)

[behrica]

referencing:
#1304

[behrica]

"I" get javadocs for JDK classes and methods in "popups", just to confirm.

[behrica]

I investigate a bit, and discovered te following, not sure if known already:

1. The current "javadoc" support of calva depens on the presence of "sources jars" on disk.
   -> me running 'clojure -X:deps mvn-pom && mvn dependency:sources' downloads and the increases (after repl restart) the situtaions where I get "javadoc popus". It seems to work for "classes" but not for "methods".

2. "io.github.clojure/java.doc" uses and downloads "javadoc jars" (not "sources jars") Most java projects publish both.

3. "my snippet" works in "more situations", then 1), but this depends on the snippet code, specially the macro in it

[behrica]

I moved the code for the snippet into is own library:
https://github.com/behrica/calva-javadoc

I realised as well that the code need to use "eval", to dynamically figure out the receiver class in an interop call such as:

(.do-something receiver ..)

This does work, but might be a security risk.