Show inline docs at point like lispy and quick-peek

[MicahElliott]

It would be great if it were easier to see see docs right at point without a new window or invoking completion. Presently, the two ways to see docs are:

• cider-clojuredocs to pop open a new window
• go to end of fn and invoke company for a completion that will pop up just the docstring

Both of those are great, but for quickest lookups, we could do what lispy and quick-peek do with an inline doc. See the screenshots/gifs on both of those.

This actually works with lispy already, but it's a heavy way to get this (and lispy does many other opinionated things), and is flaky IME.

My proposal is to slide up or down the code to fit the fn signature and short docstring (not the long clojuredocs) right into view.

Maybe quick-peek could be leveraged for this.

Or maybe there's already a simple way to get this info with company with a single keystroke?

[bbatsov]

This is a duplicate of an old issue #1982 I'm open to the idea, but I never needed this, so my incentive to tackle it was pretty low.

Company does show the documentation for the current candidate in the minibuffer. Btw, the documentation is also visible when you hover over a symbol with the mouse.

[MicahElliott]

Thanks @bbatsov! The Minibuffer functionality is great and is probably fine for this if it could expand to show the fn description too. But it's fancy about highlighting current arg, so maybe there's more to adding there than I was guessing.

And I still like the idea of showing inline (I realized when I tried flycheck-inline recently) a little better. Sorry for the dupe! Feel free to close if you prefer.

[dpsutton]

i've wanted this for a while and even played around with some of the popup libraries for emacs to accomplish this. my memory was that they all had limitations and weirdness. I wish there was something built in to emacs that was rock solid that was a "popup". I'm not sure which computer might have the patch laying around but i'll see if i can find it.

annoying things i remember are off by one errors when displaying strings such that the last character of each line was put on a new line by itself, no easily dismissable, etc.

[MicahElliott]

The lispy implementation is really nice. But is entwined with its other parts.

Something related to what you may be thinking about, @dpsutton: it'd be nice to strip out the docstring noise that shows up in the help.

There I get annoyed with the useless "Added in 1.0", "is defined in", and "[back]".

In fact, maybe just the single (first if multiple) paragraph is what I'd want for the inline. Seems like clojure core fns are usually (always?) just one paragraph. And it encourages other docstring writers to fit the most salient parts into their first similarly.

[MicahElliott]

Here's the (hacky) rudiments to get quick-peek to show the paragraph. If this isn't a terrible approach, I'll try making a PR.

(quick-peek-show (nth 10 (cider-var-info (thing-at-point 'word 'no-properties))))

Or at least it's a recipe for anyone who wants to put a binding for this and quick-peek-hide in their .init.el.

[bbatsov]

As you wish. My preference would be to avoid adding deps to CIDER if they won't be used extensively, as each dep is a form of liability that might bite you down the road. I'm assuming that quick-peek is just some simple overlay hack this can easily be implemented directly in CIDER.

[MicahElliott]

Here's a simple way to do the inlining that I'm satisfied with, for both built-ins and user-defined fns.

;; Quick-Peek for Cider
;; https://github.com/clojure-emacs/cider/issues/2968
(require 'quick-peek)
(defvar my-cider-inline-docs-opened-p nil
  "Toggle to support an inline help being open (expanded) or not.")
(defun my-cider-inline-docs-toggle ()
  "Show a fn or ns docstring's key pieces as inline overlay."
  (interactive)
  (if my-cider-inline-docs-opened-p
      (progn
	(setq my-cider-inline-docs-opened-p nil)
	(quick-peek-hide))
    ;; If not on a word, let it error
    (let* ((info    (cider-var-info (thing-at-point 'word 'no-properties)))
           ;; Built-in fns' info are indexed differently from user-defined.
	   (arglist (nrepl-dict-get info "arglists-str"))
	   (doc     (nrepl-dict-get info "doc")))
      (if doc
	  (progn
	    (quick-peek-show
	     (concat (if arglist (concat arglist "\n") "")
		     (replace-regexp-in-string "^ +" "" doc)))
	    (setq my-cider-inline-docs-opened-p t))
	(message "Unable to do doc look-up: missing docstring or invalid")))))
;; (key-chord-define-global "CD" 'my-cider-inline-docs-toggle)

Totally understand not wanting a new dep. FWIW, quick-peek is ~200 SLOC and has just a cl-lib requirement. It has a few customizations that I'd guess CIDER wouldn't care too much about:

• the ugly green default bars can be changed or eliminated (just do the latter)
• the bg color can be set (just use gray bg as in screenshot?)
• inline doc above or below (just default to above as shown)

It can also flexibly open several inlines at a time, which I don't personally find useful. Code for that could go away too, and be replaced with the toggle logic I put above.

So if we pull just the equivalent overlay code out of quick-peek, I'd think it's just a couple dozen lines of elisp. I might try to tackle that at some point, or hope someone else will. But for today, I'm going to just use the fn I posted here.

[bbatsov]

Sounds like a plan to me. :-)

[MicahElliott]

FWIW, I've been using this quick-peek approach for a few months now and I use it constantly, almost always before cider-clojuredocs (though cider-clojuredocs is still amazing and essential). Also has me wanting to make sure I've written docstrings for more fns ans nss.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contribution and understanding!

[stale]

This issues been automatically closed due to lack of activity. Feel free to re-open it if you ever come back to it.

[vemv]

Personally I show docs in the echo area:

I think it especially makes sense for Emacs which has a limited support for widgets (I do use company-mode FWIW, for completions).

Docs being longer than completions deserve a place that can accommodates them scalably. I had tried a couple popup libraries over the years but they never read as nicely as the would in other IDEs.

I'll contribute this feature to cider.el one day.