Feature Request: Better handling of full docs vs. signature help

[jdtsmith]

I started a discussion but realized an issue may be more appropriate. Consider the following:

a = np.unique(np.random.random(100), axis=2)
#     ----------- point    ^

Suppose you'd like to get the full docs for random to study while you work on building its arguments. Currently there are no good solutions to do so:

• With point on random.random two sources are vying for eldoc air time (with 1 overriding 2):
  1. signature help for unique
  2. hover information for random.
• You can set eldoc strategy to compose, to concatenate these, but as soon as you move inside the arguments of random, the docs are replaced by its signature help.

Idea: a command, e.g. eglot-display-documentation, which will:

1. request hover and signatureHelp at point or re-use the last call to these if point hasn't moved
2. take the docs from hover, if not empty and tagged with some :kind or :language, or
3. take the docs from signatureHelp's top item :documentation as a backup
4. format and put those docs in a special buffer, e.g. *eglot-help*.

The docs would stick around until such time as you replaced them by another call to eglot-display-documentation.

[joaotavora]

A discussion is more appropriate. Issues in the Eglot bug tracker are reserved for bug reports with minimum reproducible examples. Creating an issue doesn't change the amount of attention i or others can dispense on as given matter. From my part, that amount is relatively small right now at this moment, a fact for which i am very sorry but a fact of life nonetheless.

[joaotavora]

Try M-x eldoc or C-h .

[jdtsmith]

Thanks; sorry to hear don't have as much time as you'd like for eglot — thanks for all your efforts.

Try M-x eldoc or C-h .

Yes I know that one; unfortunately it simply opens the *eldoc* buffer, which exhibits the issues I mentioned ("shadowing" of signatures vs. hover, disappears on move, can't see docs and signatures at the same time, etc.). Having looked closely at eldoc I haven't seen an obvious was to do this without additional eglot support.

I do think emacs-lisp mode has a good balance: signature help on the fly at point, but ask for function documentation (which persists until you ask for some other docs).

[joaotavora]

I see, then maybe write this command and put it in your .emacs?

(defun my/persist-eldoc (interactive)
  (interactive (list t))
  (with-current-buffer eldoc--doc-buffer
    (let ((s (buffer-string)))
      (with-current-buffer (generate-new-buffer "*persisted eldoc*")
        (insert s)
        (display-buffer (current-buffer))))))

The usage of the internal variable eldoc--doc-buffer is not ideal, but I have an upcoming patch to eldoc.el that will enable you to substitute it with just (eldoc-doc-buffer).

Anyway, my opinion is that this functionality is not something to put in Eglot at all.

[bigodel]

Sorry to come to this two years later, but is there any way to get the name of the symbol ElDoc is showing documentation for? I'd like to create a buffer that's named *eldoc <function-name>*.

I was thinking about proposing an implementation of a new ElDoc command to do just that, with an optional eldoc-persistent-buffer-name-function to calculate the buffer name for the persistent documentation buffer.