Further improve button.el support for help-echo

The last change to forward-button added support for help-echo values
that are functions.  This patch fixes the arguments passed to such
functions and further adds support for help-echo values that are
forms (bug#37515).
* doc/lispref/display.texi (Button Properties): Fix description of
help-echo button property.
* lisp/button.el (button--help-echo): New function.
(forward-button): Use it.
(backward-button): Clarify help-echo reference in docstring.
* test/lisp/button-tests.el (button--help-echo-string)
(button--help-echo-form, button--help-echo-function): New tests.

1 files changed, 14 insertions, 5 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 494bf0d3f7e..61bd4ce8830 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -6607,14 +6607,23 @@ in the variable @code{button-map}, which defines @key{RET} and
 The button type.  @xref{Button Types}.
 
 @item help-echo
-@kindex help-index @r{(button property)}
-A string displayed by the Emacs tool-tip help system; by default,
-@code{"mouse-2, RET: Push this button"}.
+@kindex help-echo @r{(button property)}
+A string displayed by the Emacs tooltip help system; by default,
+@code{"mouse-2, RET: Push this button"}.  Alternatively, a function
+that returns, or a form that evaluates to, a string to be displayed or
+@code{nil}.  For details see @ref{Text help-echo}.
+
+The function is called with three arguments, @var{window},
+@var{object}, and @var{pos}.  The second argument, @var{object}, is
+either the overlay that had the property (for overlay buttons), or the
+buffer containing the button (for text property buttons).  The other
+arguments have the same meaning as for the special text property
+@code{help-echo}.
 
 @item follow-link
 @kindex follow-link @r{(button property)}
-The follow-link property, defining how a @key{mouse-1} click behaves
-on this button, @xref{Clickable Text}.
+The @code{follow-link} property, defining how a @key{mouse-1} click
+behaves on this button, @xref{Clickable Text}.
 
 @item button
 @kindex button @r{(button property)}