From 489bca19b7a55ba00dbc1d917cd8832268cebcee Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Sun, 25 Sep 2022 14:26:40 +0200
Subject: [PATCH] Improve shortdoc documentation

* doc/emacs/help.texi (Name Help):
* doc/lispref/help.texi (Documentation Groups): Refer to
'shortdoc' convenience alias instead of 'shortdoc-display-group'.
* lisp/emacs-lisp/shortdoc.el: Add Commentary.
(shortdoc-next, shortdoc-previous)
(shortdoc-next-section, shortdoc-previous-section): Doc fixes.
---
 doc/emacs/help.texi         |  9 ++++-----
 doc/lispref/help.texi       |  2 +-
 lisp/emacs-lisp/shortdoc.el | 25 +++++++++++++++++--------
 3 files changed, 22 insertions(+), 14 deletions(-)

diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 84b082825c2..6d9c028b742 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -311,12 +311,11 @@ doc string to display.  In that case, if
 to load the file in which the function is defined to see whether
 there's a doc string there.
 
-@findex shortdoc-display-group
+@findex shortdoc
   You can get an overview of functions relevant for a particular topic
-by using the @kbd{M-x shortdoc-display-group} 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.
+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.
 
 @kindex C-h v
 @findex describe-variable
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 154a7abeb63..65ad5f05542 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -827,7 +827,7 @@ if the user types the help character again.
 
 Emacs can list functions based on various groupings.  For instance,
 @code{string-trim} and @code{mapconcat} are ``string'' functions, so
-@kbd{M-x shortdoc-display-group RET string RET} will give an overview
+@kbd{M-x shortdoc RET string RET} will give an overview
 of functions that operate on strings.
 
 The documentation groups are created with the
diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el
index b5c99cf2c9a..6d61ed4ac16 100644
--- a/lisp/emacs-lisp/shortdoc.el
+++ b/lisp/emacs-lisp/shortdoc.el
@@ -22,6 +22,15 @@
 
 ;;; Commentary:
 
+;; This package lists functions based on various groupings.
+;;
+;; For instance, `string-trim' and `mapconcat' are `string' functions,
+;; so `M-x shortdoc RET string RET' will give an overview of functions
+;; that operate on strings.
+;;
+;; The documentation groups are created with the
+;; `define-short-documentation-group' macro.
+
 ;;; Code:
 
 (require 'seq)
@@ -1533,27 +1542,27 @@ Example:
     (setq arg (1- arg))))
 
 (defun shortdoc-next (&optional arg)
-  "Move cursor to the next function.
-With ARG, do it that many times."
+  "Move point to the next function.
+With prefix argument ARG, do it that many times."
   (interactive "p" shortdoc-mode)
   (shortdoc--goto-section arg 'shortdoc-function))
 
 (defun shortdoc-previous (&optional arg)
-  "Move cursor to the previous function.
-With ARG, do it that many times."
+  "Move point to the previous function.
+With prefix argument ARG, do it that many times."
   (interactive "p" shortdoc-mode)
   (shortdoc--goto-section arg 'shortdoc-function t)
   (backward-char 1))
 
 (defun shortdoc-next-section (&optional arg)
-  "Move cursor to the next section.
-With ARG, do it that many times."
+  "Move point to the next section.
+With prefix argument ARG, do it that many times."
   (interactive "p" shortdoc-mode)
   (shortdoc--goto-section arg 'shortdoc-section))
 
 (defun shortdoc-previous-section (&optional arg)
-  "Move cursor to the previous section.
-With ARG, do it that many times."
+  "Move point to the previous section.
+With prefix argument ARG, do it that many times."
   (interactive "p" shortdoc-mode)
   (shortdoc--goto-section arg 'shortdoc-section t)
   (forward-line -2))
-- 
2.39.2