eldoc is overloaded with full documentation

[jdtsmith]

TLDR: IMO, having Eldoc display full documentation in addition to function signatures is overloading it. In emacs-lisp mode, for example, eldoc is used to display function signatures in the echo area, but a separate, persistent, on-demand *Help* buffer is used for function help.

---

I get reasonable documentation and signature help for Python with pylsp. Signature help is especially convenient because it highlights positional arguments as you type them. Very cool.

But the docs are a bit more problematic at the moment. A very common workflow for me in other tools is to open the full documentation for a function/method in a separate buffer (e.g. *eldoc*), then use the minibuffer for the rich signature help as you compose a call, consulting the documentation in the other buffer. Unfortunately with eglot & eldoc, both signature help and documentation go to the same place(s): minibuffer and *eldoc* buffer. So as soon as you open a function call (e.g. np.unique -> np.unique() the hover-based documentation in *eldoc* is erased and replaced with signature help.

Is there a way to send signatureHelp only to the minibuffer, and full documentation only to the *eldoc* (or some other) buffer, and prevent the latter from being erased when point moves?

Ideally the setup would be:

1. Signature help always shows up via timer/eldoc when in the arguments of a function call.
2. Full documentation help on the symbol is requested only on demand (e.g. via C-h .) and placed in its own buffer. It does not disappear until another such request is made. I.e. opt-in to documentation.
3. [Bonus] If help is request while inside method/function call arguments, help for that method/function is provided.

Interestingly, #3 may be straightforward, because the same full documentation is provided in the top-level :documentation for the textDocument/hover response as for the :signature's top-level :documentation for the textDocument/signatureHelp response. So honestly it's enough for me to show the :documentation inside of the signatureHelp response, and just disable hover. But right now, eglot--sig-info just plucks out the first line of the documentation.

I know this has been discussed quite a bit; appreciate any thoughts.

[jdtsmith]

Something hacky like this works pretty well (in eglot--sig-info):

   (eglot--dbind ((SignatureInformation) label documentation parameters activeParameter) sig
     (if (stringp documentation)
	 (with-current-buffer (get-buffer-create "*EGLOT-SIG-HELP*")
	   (erase-buffer)
	   (save-excursion
	     (insert label "\n"
		     (eglot--format-markup documentation)))))

[jdtsmith]

Except the formatting isn't quite right. But the idea works.

[jdtsmith]

See #931