Merge remote-tracking branch 'origin/master' into feature/android

2 files changed, 36 insertions, 0 deletions

diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 2513e6be271..945e12a05d2 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -317,6 +317,16 @@ by using the @kbd{M-x shortdoc} command.  This will prompt you for an
 area of interest, e.g., @code{string}, and pop you to a buffer where
 many of the functions relevant for handling strings are listed.
 
+You can also request that documentation of functions and commands
+shown in @file{*Help*} buffers popped by @kbd{C-h f} includes examples
+of their use.  To that end, add the following to your initialization
+file (@pxref{Init File}):
+
+@example
+(add-hook 'help-fns-describe-function-functions
+          #'shortdoc-help-fns-examples-function)
+@end example
+
 @kindex C-h v
 @findex describe-variable
   @kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 59b6b6dab1d..d5e4e1c31d3 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -989,3 +989,29 @@ in the function group to insert the function into.
 If @var{group} doesn't exist, it will be created.  If @var{section}
 doesn't exist, it will be added to the end of the function group.
 @end defun
+
+You can also query the examples of use of functions defined in
+shortdoc groups.
+
+@defun shortdoc-function-examples function
+This function returns all shortdoc examples for @var{function}.  The
+return value is an alist with items of the form
+@w{@code{(@var{group} . @var{examples})}}, where @var{group} is a
+documentation group where @var{function} appears, and @var{examples}
+is a string with the examples of @var{function}s use as defined in
+@var{group}.
+
+@code{shortdoc-function-examples} returns @code{nil} if @var{function}
+is not a function or if it doesn't have any shortdoc examples.
+@end defun
+
+@vindex help-fns-describe-function-functions
+@defun shortdoc-help-fns-examples-function function
+This function queries the registered shortdoc groups and inserts
+examples of use of a given Emacs Lisp @var{function} into the current
+buffer.  It is suitable for addition to the
+@code{help-fns-describe-function-functions} hook, in which case
+examples from shortdoc of using a function will be displayed in the
+@file{*Help*} buffer when the documentation of the function is
+requested.
+@end defun