Subject: Re: bug#77169: [PATCH] New Eldoc function `help-at-pt-eldoc-function'

From: Eli Zaretskii <[email-masked]>
Date: Sun, 23 Mar 2025 08:07:30 +0200

> From: Daniel Mendler <[email-masked]>
> Cc: [email-masked]
> Date: Sat, 22 Mar 2025 21:56:27 +0100
> 
> >> > Also, shouldn't we have a user option to turn this on in ElDoc?
> >> 
> >> Not sure if we need an option given that it is easy to add the function
> >> to the list, or remove it, if the function is enabled by default.
> >
> > It might be easy fore you and me, but not for users who are not Lisp
> > programmers.
> 
> Okay. I have attached an updated version of the patch to this mail. I
> have added a customization option (off by default) and a NEWS entry.

Thanks.

> --- a/etc/NEWS
> +++ b/etc/NEWS
> @@ -415,6 +415,11 @@ need to set it with 'setopt' for it to take an effect.  If the docstring
>  doesn't already mention 'setopt', the 'describe-variable' command will
>  now add a note about this automatically.
>  
> +---

This should be "+++", since you've updated the manuals.

> +(defcustom eldoc-help-at-pt nil
> +  "Show `help-at-pt-kbd-string' at point via Eldoc.

"If non-nil, show `help-at-pt-kbd-string' at point via Eldoc."

> +This setting is an alternative to `help-at-pt-display-when-idle'.  If
> +the variable is t, enable the `eldoc-help-at-pt-function'."

"Enable" is inaccurate, since it's enabled by default, it just doesn't
do anything when the variable is nil.  So something like

  If the value is non-nil, `eldoc-help-at-pt-function' will show
  help-at-point via Eldoc.

> -(defvar eldoc-documentation-functions nil
> +(defvar eldoc-documentation-functions (list #'eldoc-help-at-pt-function)
>    "Hook of functions that produce doc strings.
>  
>  A doc string is typically relevant if point is on a function-like
> @@ -957,6 +963,12 @@ eldoc-print-current-symbol-info
>               (setq eldoc--last-request-state token)
>               (eldoc--invoke-strategy nil))))))
>  
> +(defun eldoc-help-at-pt-function (&rest _)

I thought symbols that end in "-function" are usually variables whose
value is the function, is that not so?  So maybe call this
eldoc-show-help-at-pt instead?

> --- a/lisp/help-at-pt.el
> +++ b/lisp/help-at-pt.el
> @@ -191,7 +191,11 @@ help-at-pt-display-when-idle
>  enabling buffer local values.  It sets the actual value to nil.
>  Thus, Custom distinguishes between a nil value and other values
>  that disable the feature, which Custom identifies with `never'.
> -The default is `never'."
> +The default is `never'.
> +
> +Eldoc uses the echo area to display help at point.

I'd say "Eldoc uses the echo area to display documentation" instead,
since the conflict between help-at-pt-display-when-idle and Eldoc is
due to the use of echo-area, not because they both show help-at-pt.