Improve documentation of the 'abbrev-suggest' feature

* lisp/abbrev.el (abbrev-suggest, abbrev-suggest-hint-threshold)
(abbrev-suggest-show-report): Improve wording of the doc strings.

* doc/emacs/abbrevs.texi (Abbrevs Suggestions): Fix the typo in
the node name.  Improve wording.
* doc/emacs/emacs.texi (Top): Add the new node in the @detailmenu
section.

* etc/NEWS: Improve wording of the NEWS entry for
'abbrev-suggest'.

4 files changed, 41 insertions, 36 deletions

diff --git a/doc/emacs/abbrevs.texi b/doc/emacs/abbrevs.texi
index 0dda977833f..e3766aae9e8 100644
--- a/doc/emacs/abbrevs.texi
+++ b/doc/emacs/abbrevs.texi
@@ -28,7 +28,7 @@ Automatic Typing}.
 * Abbrev Concepts::   Fundamentals of defined abbrevs.
 * Defining Abbrevs::  Defining an abbrev, so it will expand when typed.
 * Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
-* Abbrevs Suggestions:: Get suggestions about defined abbrevs.
+* Abbrevs Suggestions:: Get automatic suggestions about defined abbrevs.
 * Editing Abbrevs::   Viewing or editing the entire list of defined abbrevs.
 * Saving Abbrevs::    Saving the entire list of abbrevs for another session.
 * Dynamic Abbrevs::   Abbreviations for words already in the buffer.
@@ -224,34 +224,35 @@ changing this function you can make arbitrary changes to
 the abbrev expansion.  @xref{Abbrev Expansion,,, elisp, The Emacs Lisp
 Reference Manual}.
 
-@node Abbrev Suggestions
-@section Abbrev Suggestions
+@node Abbrevs Suggestions
+@section Abbrevs Suggestions
 
   You can get abbrev suggestions when you manually type text for which
 there is currently an active defined abbrev.  For example, if there is
 an abbrev @samp{foo} with the expansion @samp{find outer otter}, and
-you manually type @samp{find outer otter}, the abbrev suggestion
-feature will notice this and show a hint in the echo area when you
-have stopped typing.
+you manually type @samp{find outer otter}, Emacs can notice this and
+show a hint in the echo area when you have stopped typing.
 
 @vindex abbrev-suggest
-  Enable the abbrev suggestion feature by setting
-@code{abbrev-suggest} to @code{t}.
+  To enable the abbrev suggestion feature, customize the option
+@code{abbrev-suggest} to a non-@code{nil} value.
 
 @vindex abbrev-suggest-hint-threshold
-  Controls when to suggest an abbrev to the user.  The variable
-defines the number of characters that the user must save in order to
-get a suggestion.  For example, if the user types @samp{foo bar}
-(seven characters) and there is an abbrev @samp{fubar} defined (five
-characters), the user will not get any suggestion unless the threshold
-is set to the number 2 or lower.  With the default value 3, the user
-would not get any suggestion, because the savings in using the abbrev
-are not above the threshold.  If you always want to get abbrev
-suggestions, set this variable to 0.
+  The variable @code{abbrev-suggest-hint-threshold} controls when to
+suggest an abbrev to the user.  This variable defines the minimum
+savings (in terms of the number of characters the user will not have
+to type) required for Emacs to suggest using an abbrev.  For example,
+if the user types @samp{foo bar} (seven characters) and there is an
+abbrev @samp{fubar} defined (five characters), the user will not get
+any suggestion unless the threshold is set to the number 2 or lower.
+With the default value 3, the user would not get any suggestion in
+this example, because the savings in using the abbrev are below
+the threshold.  If you always want to get abbrev suggestions, set this
+variable's value to zero.
 
 @findex abbrev-suggest-show-report
-  The command @code{abbrev-suggest-show-report} can be used to show a
-buffer with all abbrev suggestions from the current editing session.
+  The command @code{abbrev-suggest-show-report} displays a buffer with
+all the abbrev suggestions shown during the current editing session.
 This can be useful if you get several abbrev suggestions and don't
 remember them all.
 
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index 6aed7bd92a5..566229b2f32 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -908,6 +908,7 @@ Abbrevs
 * Abbrev Concepts::     Fundamentals of defined abbrevs.
 * Defining Abbrevs::    Defining an abbrev, so it will expand when typed.
 * Expanding Abbrevs::   Controlling expansion: prefixes, canceling expansion.
+* Abbrevs Suggestions:: Get automatic suggestions about defined abbrevs.
 * Editing Abbrevs::     Viewing or editing the entire list of defined abbrevs.
 * Saving Abbrevs::      Saving the entire list of abbrevs for another session.
 * Dynamic Abbrevs::     Abbreviations for words already in the buffer.
diff --git a/etc/NEWS b/etc/NEWS
index 0cbbae41861..202cd689d33 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1274,12 +1274,12 @@ of conditionals.
 ** Abbrev mode
 
 +++
-*** Abbrev can now suggest pre-existing abbrevs based on typed text.
+*** Emacs can now suggest to use an abbrev based on text you type.
 A new user option, 'abbrev-suggest', enables the new abbrev suggestion
-feature.  When enabled, if a user manually type a piece of text that
-could have been written by using an abbrev, a hint will be displayed
-in the echo area, mentioning the abbrev that could have been used
-instead.
+feature.  When enabled, if a user manually types a piece of text that
+could have saved enough typing by using an abbrev, a hint will be
+displayed in the echo area, mentioning the abbrev that could have been
+used instead.
 
 
 * New Modes and Packages in Emacs 28.1
diff --git a/lisp/abbrev.el b/lisp/abbrev.el
index 75cc43941f4..dc52a220125 100644
--- a/lisp/abbrev.el
+++ b/lisp/abbrev.el
@@ -825,22 +825,23 @@ see `define-abbrev' for details."
 Takes no argument and should return the abbrev symbol if expansion took place.")
 
 (defcustom abbrev-suggest nil
-  "Non-nil means suggest abbrevs to the user.
-By enabling this option, if abbrev mode is enabled and if the
-user has typed some text that exists as an abbrev, suggest to the
-user to use the abbrev by displaying a message in the echo area."
+  "Non-nil means suggest using abbrevs to save typing.
+When abbrev mode is active and this option is non-nil, Emacs will
+suggest in the echo area to use an existing abbrev if doing so
+will save enough typing.  See `abbrev-suggest-hint-threshold' for
+the definition of \"enough typing\"."
     :type 'boolean
     :version "28.1")
 
 (defcustom abbrev-suggest-hint-threshold 3
-  "Threshold for when to inform the user that there is an abbrev.
-The threshold is the number of characters that differ between the
-length of the abbrev and the length of the expansion.  The
-thinking is that if the expansion is only one or a few characters
+  "Threshold for when to suggest to use an abbrev to save typing.
+The threshold is the amount of typing, in terms of the number of
+characters, that would be saved by using the abbrev.  The
+thinking is that if the expansion is only a few characters
 longer than the abbrev, the benefit of informing the user is not
-that big.  If you always want to be informed, set this value to
-`0' or less.  This setting only applies if `abbrev-suggest' is
-non-nil."
+significant.  If you always want to be informed about existing
+abbrevs for the text you type, set this value to zero or less.
+This setting only applies if `abbrev-suggest' is non-nil."
     :type 'number
     :version "28.1")
 
@@ -945,7 +946,9 @@ typed."
       total))
 
 (defun abbrev-suggest-show-report ()
-  "Show the user a report of abbrevs he could have used."
+  "Show a buffer with the list of abbrevs you could have used.
+This shows the abbrevs you've \"missed\" because you typed the
+full text instead of the abbrevs that expand into that text."
   (interactive)
   (let ((totals (abbrev--suggest-get-totals))
         (buf (get-buffer-create "*abbrev-suggest*")))