; Fix last change

* lisp/emacs-lisp/shortdoc.el (shortdoc-help-fns-examples-function)
(shortdoc-function-examples): Fix compilation warning and add an
empty line before the examples.

* lisp/emacs-lisp/shortdoc.el (shortdoc--insert-group-in-buffer)
(shortdoc-function-examples)
(shortdoc-help-fns-examples-function):
* etc/NEWS:
* doc/lispref/help.texi (Documentation Groups):
* doc/emacs/help.texi (Name Help): Improve documentation of
the last change.  (Bug#61877)

4 files changed, 41 insertions, 39 deletions

diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 10c007eb635..945e12a05d2 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -316,10 +316,11 @@ there's a doc string there.
 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.
-Here's an example you can include in your initialization file
-(@pxref{Init File}) that uses @code{shortdoc} to insert Emacs Lisp
-function examples into regular @file{*Help*} buffers when you use
-@kbd{C-h f}:
+
+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
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 3175f66122e..d5e4e1c31d3 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -995,23 +995,23 @@ shortdoc groups.
 
 @defun shortdoc-function-examples function
 This function returns all shortdoc examples for @var{function}.  The
-result is an alist with items of the form
-
-@example
-(@var{group} . @var{examples})
-@end example
-
-@noindent
-where @var{group} is a documentation group where @var{function}
-appears in and @var{examples} is a string with the examples of use of
-@var{function} defined in @var{group}.
+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 contain shortdoc information.
+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 documentation groups and inserts
-examples of use of a given Emacs Lisp function into the current
-buffer.
+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
diff --git a/etc/NEWS b/etc/NEWS
index 5f51b801774..e43aac614c9 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -224,15 +224,15 @@ This replaces 'doc-view-svg-foreground' and 'doc-view-svg-background'.
 
 +++
 *** New function 'shortdoc-function-examples'.
-This function queries the registered documentation groups and returns
-examples of use of a given Emacs Lisp function.
+This function returns examples of use of a given Emacs Lisp function
+from the available shortdoc information.
 
 +++
 *** New function 'shortdoc-help-fns-examples-function'.
-This function queries the registered documentation groups and inserts
-examples of use of a given Emacs Lisp function into the current
-buffer.  If you want to insert Emacs Lisp function examples into
-regular *Help* buffers when you use 'describe-function', add the
+This function inserts into the current buffer examples of use of a
+given Emacs Lisp function, which it gleans from the shortdoc
+information.  If you want 'describe-function' ('C-h f') to insert
+examples of using the function into regular *Help* buffers, add the
 following to you init file:
 
     (add-hook 'help-fns-describe-function-functions
diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el
index cf66a43fc35..6e3ebc7c6a2 100644
--- a/lisp/emacs-lisp/shortdoc.el
+++ b/lisp/emacs-lisp/shortdoc.el
@@ -1455,7 +1455,8 @@ If SAME-WINDOW, don't pop to a new window."
     (beginning-of-line)))
 
 (defun shortdoc--insert-group-in-buffer (group &optional buf)
-  "Insert a short documentation summary for functions in GROUP in buffer BUF."
+  "Insert a short documentation summary for functions in GROUP in buffer BUF.
+BUF defaults to the current buffer if nil or omitted."
   (with-current-buffer (or buf (current-buffer))
     (let ((inhibit-read-only t)
           (prev nil))
@@ -1593,10 +1594,10 @@ function's documentation in the Info manual"))
 (defun shortdoc-function-examples (function)
   "Return all shortdoc examples for FUNCTION.
 The result is an alist with items of the form (GROUP . EXAMPLES),
-where GROUP is a shortdoc group where FUNCTION appears in and
+where GROUP is a shortdoc group where FUNCTION appears, and
 EXAMPLES is a string with the usage examples of FUNCTION defined
 in GROUP.  Return nil if FUNCTION is not a function or if it
-doesn't contain shortdoc information."
+doesn't has any shortdoc information."
   (let ((groups (and (symbolp function)
                      (shortdoc-function-groups function)))
         (examples nil))
@@ -1605,28 +1606,28 @@ doesn't contain shortdoc information."
        (with-temp-buffer
          (shortdoc--insert-group-in-buffer group)
          (goto-char (point-min))
-         (setq match (text-property-search-forward
-                      'shortdoc-example function t))
-         (push `(,group . ,(string-trim
-                            (buffer-substring-no-properties
-                             (prop-match-beginning match)
-                             (prop-match-end match))))
-               examples)))
+         (let ((match (text-property-search-forward
+                       'shortdoc-example function t)))
+           (push `(,group . ,(string-trim
+                              (buffer-substring-no-properties
+                               (prop-match-beginning match)
+                               (prop-match-end match))))
+                 examples))))
      groups)
     examples))
 
 (defun shortdoc-help-fns-examples-function (function)
   "Insert Emacs Lisp examples for FUNCTION into the current buffer.
-You can add this function to the
-`help-fns-describe-function-functions' list to show function
-example documentation in *Help* buffers."
+You can add this function to the `help-fns-describe-function-functions'
+hook to show examples of using FUNCTION in *Help* buffers produced
+by \\[describe-function]."
   (let ((examples (shortdoc-function-examples function))
         (times 0))
     (dolist (example examples)
       (when (zerop times)
         (if (eq (length examples) 1)
-            (insert "  Example:\n\n")
-          (insert "  Examples:\n\n")))
+            (insert "\n  Example:\n\n")
+          (insert "\n  Examples:\n\n")))
       (setq times (1+ times))
       (insert "  ")
       (insert (cdr example))