From: Lars Ingebrigtsen <larsi@gnus.org>
Date: Fri, 7 Aug 2020 11:36:50 +0000 (+0200)
Subject: Add some documentation for widget-describe and button-describe
X-Git-Tag: emacs-28.0.90~6766
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=1545f28a98e143f027bd9cf69a2f0d323ad49ed3;p=emacs.git

Add some documentation for widget-describe and button-describe

* doc/emacs/help.texi (Key Help): Document button-describe and
widget-describe.

* lisp/button.el (push-button): Mention button-describe.

* lisp/cus-edit.el (Custom-newline): Mention widget-describe (bug#139).
---

diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 167c32c4d21..06ad5a583d2 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -220,6 +220,16 @@ documentation string of the command it runs.
 command is not on any key, that means you must use @kbd{M-x} to run
 it.  @kbd{C-h w} runs the command @code{where-is}.
 
+@findex button-describe
+@findex widget-describe
+  Some modes in Emacs use various buttons (@pxref{Buttons,,,elisp, The
+Emacs Lisp Reference Manual}) and widgets
+(@pxref{Introduction,,,widget, Emacs Widgets}) that can be clicked to
+perform some action.  To find out what function is ultimately invoked
+by these buttons, Emacs provides the @code{button-describe} and
+@code{widget-describe} commands, that should be run with point over
+the button.
+
 @node Name Help
 @section Help by Command or Variable Name
 
diff --git a/etc/NEWS b/etc/NEWS
index 201c0b58cda..dcd8ea6a9b3 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -123,8 +123,8 @@ horizontal movements now stop at the edge of the board.
 setting the variable 'auto-save-visited-mode' buffer-locally to nil.
 
 ** New commands to describe buttons and widgets have been added.
-'describe-widget' (on a widget) will pop up a help buffer and give a
-description of the properties.  Likewise 'describe-button' does the
+'widget-describe' (on a widget) will pop up a help buffer and give a
+description of the properties.  Likewise 'button-describe' does the
 same for a button.
 
 
diff --git a/lisp/button.el b/lisp/button.el
index 941b9fe720a..03ab59b109c 100644
--- a/lisp/button.el
+++ b/lisp/button.el
@@ -464,8 +464,12 @@ see).
 POS defaults to point, except when `push-button' is invoked
 interactively as the result of a mouse-event, in which case, the
 mouse event is used.
+
 If there's no button at POS, do nothing and return nil, otherwise
-return t."
+return t.
+
+To get a description of what function will called when pushing a
+butting, use the `button-describe' command."
   (interactive
    (list (if (integerp last-command-event) (point) last-command-event)))
   (if (and (not (integerp pos)) (eventp pos))
diff --git a/lisp/cus-edit.el b/lisp/cus-edit.el
index 1942f25e891..16695967dfa 100644
--- a/lisp/cus-edit.el
+++ b/lisp/cus-edit.el
@@ -4841,7 +4841,10 @@ The format is suitable for use with `easy-menu-define'."
   (error "You can't edit this part of the Custom buffer"))
 
 (defun Custom-newline (pos &optional event)
-  "Invoke button at POS, or refuse to allow editing of Custom buffer."
+  "Invoke button at POS, or refuse to allow editing of Custom buffer.
+
+To see what function the widget will call, use the
+`widget-describe' command."
   (interactive "@d")
   (let ((button (get-char-property pos 'button)))
     ;; If there is no button at point, then use the one at the start