search

clojure-emacs / cider

The Clojure Interactive Development Environment that Rocks for Emacs
https://cider.mx
GNU General Public License v3.0
3.55k stars 645 forks source link

Make it possible to add remote JavaDoc URLs via CIDER's config #2969

Open bbatsov opened 3 years ago

bbatsov commented 3 years ago

For JavaDoc to work properly for third-party libraries we need to register their JavaDoc like this:

(javadoc/add-remote-javadoc "com.amazonaws." "http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/")
(javadoc/add-remote-javadoc "org.apache.kafka." "https://kafka.apache.org/090/javadoc/")

For the sake of convenience we can add some configuration map that gets evaluated when a REPL gets created, or something along those lines (we already have similar functionality for requiring code on REPL start).

NightMachinery commented 3 years ago

I am trying to get the JavaDocs for an external library I have imported. I patched the handler to show me the URL it found for the JavaDocs:

(defun cider-javadoc-handler (symbol-name)
  "Invoke the nREPL \"info\" op on SYMBOL-NAME if available."
  (when symbol-name
    (let* ((info (cider-var-info symbol-name))
           (url (nrepl-dict-get info "javadoc")))
      (if url
          (progn
            (message "javadoc found: %s" url)
            (browse-url url))
        (user-error "No Javadoc available for %s" symbol-name)))))
javadoc found: ezvcard/VCard.html#getTelephoneNumbers()

But of course, ezvcard/VCard.html#getTelephoneNumbers() is invalid, and browse-url silently ignores it on my machine. Is this a bug? Should I "register" the remote JavaDocs? (How do I find the URL for this?!)

Shouldn't CIDER emit some helpful error messages in this case?

vemv commented 3 years ago

Perhaps ezvcard/VCard.html denotes a resource? i.e. (clojure.java.io/resource "ezvcard/VCard.html") returns non-nil in your machine?

NightMachinery commented 3 years ago

@vemv commented on Oct 7, 2021, 8:51 AM GMT+3:30:

Perhaps ezvcard/VCard.html denotes a resource? i.e. (clojure.java.io/resource "ezvcard/VCard.html") returns non-nil in your machine?

No, it returns nil.

vemv commented 3 years ago

OK

I am trying to get the JavaDocs for an external library I have imported.

How did you import it?

NightMachinery commented 3 years ago

@vemv commented on Oct 7, 2021, 11:39 AM GMT+3:30:

OK

I am trying to get the JavaDocs for an external library I have imported.

How did you import it?

(ns NightMachinary.vcard-to-json
  (:gen-class))

(import (ezvcard Ezvcard VCard))

You can find the project here.

vemv commented 3 years ago

That simply imports the class, but a Java class (as found in a normal .jar) doesn't include javadocs or sources.

We're already tracking this work for the next CIDER release (for ~3 weeks from today). If you are curious you can check out https://github.com/clojure-emacs/enrich-classpath/ .

Our intent is to abstract these away so I'm not recommending users to fiddle a lot with config - this work will be done for you soon enough!