Re: Documentation by function beyond elisp

[João Távora]

On Fri, Mar 10, 2023 at 2:51 PM Eshel Yaron <me@eshelyaron.com> wrote:
>
> Yuri Khan <yuri.v.khan@gmail.com> writes:
>
> > On Fri, 10 Mar 2023 at 16:12, Ihor Radchenko <yantar92@posteo.net> wrote:
> >>
> >> Yuri Khan <yuri.v.khan@gmail.com> writes:
> >>
> >> > For languages other than Elisp, this is handled by the language
> >> > server. Eglot arranges for language-server-provided function help to
> >> > be displayed by ElDoc.
> >>
> >> What about an equivalent of the *Help* buffer?
> >
> > Well, what about it? You move the point to an identifier. Its
> > signature and a few lines of documentation are shown in the echo area.
> > You invoke (eldoc-doc-buffer) and see the whole documentation.
> >
> > It may be a bit inconvenient that the content of that buffer changes
> > as you move point to a different identifier. But that can be worked
> > around with (clone-buffer).
>
> IMO ElDoc and Help and two pretty different features, each with its own
> use and purpose.

They are different in implementation, but there is definitely overlap,
and not in small amount.  I'm not saying this is ideal, but that's
what it is. Both features show documentation for language elements.

One difference is that it is just much easier to hook up ElDoc to
multiple asynchronous and synchronous documentation providing features,
such as Eglot's LSP interface, but also SLY, SLIME, CIDER as examples.

Also, using help-mode, the major mode must do all the window
management and documentation rendering.  It's not immediately
clear if it can be used to exert generic control over how
documentation is displayed, like eldoc.el can.  It's also not
immediately clear how to use it with asynchronous documentation
sources.

Eldoc.el lives in lisp/emacs-lisp, but it was effectively already
being used for other languages and modes long before I reworked
some of its interfaces.  The manual is very underdeveloped, but
IMHO a much more promising feature.  I myself have never used *Help*
for anything but Emacs lisp, where I do appreciate it immensely.

> Eglot integrates with ElDoc but not with Help AFAIU,
> but language-specific packages can (and should!) integrate
> with both of these facilities.

I'm not saying the contrary, but I'd say that for a new mode
for language-x it's easier to setup Eldoc with an external
documentation-producing program, an inferior process (like
SLY/CIDER) leave it to LSP via Eglot.  Fully fleshing out a
*Help* renderer like you did in sweeprolog.el seems a lot
more work.

João