Show information about the suffix at point in the echo area

Display the same information, using a tooltip, when the mouse
is over a command button.

Closes #282.

2 files changed, 53 insertions, 2 deletions

diff --git a/docs/transient.org b/docs/transient.org
index 6816a91..503e4dc 100644
--- a/docs/transient.org
+++ b/docs/transient.org
@@ -461,7 +461,8 @@ Also see [[* Common Suffix Commands]].
 - User Option: transient-enable-popup-navigation ::
 
   This option controls whether navigation commands are enabled in the
-  transient popup buffer.
+  transient popup buffer.  If the value is ~verbose~, additionally show
+  brief documentation about the command under point in the echo area.
 
   While a transient is active the transient popup buffer is not the
   current buffer, making it necessary to use dedicated commands to act
@@ -1869,6 +1870,25 @@ functions use ~describe-function~.
   window.  Select the help window, and make the help buffer current
   and return it.
 
+- Function: transient-show-summary obj &optional return ::
+
+  This generic function shows or, if optional RETURN is non-~nil~,
+  returns a brief summary about the command at point or hovered with
+  the mouse.
+
+  This function is called when the mouse is moved over a command and
+  (if the value of ~transient-enable-popup-navigation~ is ~verbose~) when
+  the user navigates to a command using the keyboard.
+
+  If OBJ's ~summary~ slot is a string, that is used.  If ~summary~ is a
+  function, that is called with OBJ as the only argument and the
+  returned string is used.  If ~summary~ is or returns something other
+  than a string or nil, no summary is shown.  If ~summary~ is or returns
+  ~nil~, the first line of the documentation string is used, if any.
+
+  If RETURN is non-~nil~, this function returns the summary instead of
+  showing it.  This is used when a tooltip is needed.
+
 ** Prefix Slots
 
 - ~show-help~, ~man-page~ or ~info-manual~ can be used to specify the
@@ -1972,6 +1992,11 @@ Also see [[*Suffix Classes]].
   unspecified, the prefix controls how help is displayed for its
   suffixes.  See also function ~transient-show-help~.
 
+- ~summary~ The summary displayed in the echo area, or as a tooltip.
+  If this is ~nil~, which it usually should be, the first line of the
+  documentation string is used instead.  See ~transient-show-summary~
+  for details.
+
 *** Slots of ~transient-infix~
 :PROPERTIES:
 :UNNUMBERED: notoc
diff --git a/docs/transient.texi b/docs/transient.texi
index 594871a..59f9278 100644
--- a/docs/transient.texi
+++ b/docs/transient.texi
@@ -618,7 +618,8 @@ the absolute value).
 
 @defopt transient-enable-popup-navigation
 This option controls whether navigation commands are enabled in the
-transient popup buffer.
+transient popup buffer.  If the value is @code{verbose}, additionally show
+brief documentation about the command under point in the echo area.
 
 While a transient is active the transient popup buffer is not the
 current buffer, making it necessary to use dedicated commands to act
@@ -2125,6 +2126,25 @@ window.  Select the help window, and make the help buffer current
 and return it.
 @end defmac
 
+@defun transient-show-summary obj &optional return
+This generic function shows or, if optional RETURN is non-@code{nil},
+returns a brief summary about the command at point or hovered with
+the mouse.
+
+This function is called when the mouse is moved over a command and
+(if the value of @code{transient-enable-popup-navigation} is @code{verbose}) when
+the user navigates to a command using the keyboard.
+
+If OBJ's @code{summary} slot is a string, that is used.  If @code{summary} is a
+function, that is called with OBJ as the only argument and the
+returned string is used.  If @code{summary} is or returns something other
+than a string or nil, no summary is shown.  If @code{summary} is or returns
+@code{nil}, the first line of the documentation string is used, if any.
+
+If RETURN is non-@code{nil}, this function returns the summary instead of
+showing it.  This is used when a tooltip is needed.
+@end defun
+
 @node Prefix Slots
 @section Prefix Slots
 
@@ -2252,6 +2272,12 @@ the styling there.  @code{face} is appended using @code{add-face-text-property}.
 @code{show-help} A function used to display help for the suffix.  If
 unspecified, the prefix controls how help is displayed for its
 suffixes.  See also function @code{transient-show-help}.
+
+@item
+@code{summary} The summary displayed in the echo area, or as a tooltip.
+If this is @code{nil}, which it usually should be, the first line of the
+documentation string is used instead.  See @code{transient-show-summary}
+for details.
 @end itemize
 
 @anchor{Slots of @code{transient-infix}}