; Improve documentation of new Imenu features

* doc/emacs/programs.texi (Imenu): Update documentation of
'imenu-flatten'.

* etc/NEWS: Fix wording of 'imenu-flatten's entry.

* lisp/imenu.el (imenu-flatten): Fix doc string and value
descriptions.  (Bug#70846)

3 files changed, 50 insertions, 23 deletions

diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 8ab5033795d..b944d24d91f 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -331,20 +331,43 @@ a negative argument moves back to the start of a sentence.
 @cindex index of buffer definitions
 @cindex buffer definitions index
 
-  The Imenu facility offers a way to find the major definitions in
-a file by name.  It is also useful in text formatter major modes,
-where it treats each chapter, section, etc., as a definition.
-(@xref{Xref}, for a more powerful feature that handles multiple files
-together.)
+  The Imenu facility offers a way to find the major definitions in a
+file by name.  It is useful both in programming-language major modes,
+where the definitions are variables, functions, etc., and in text
+formatter major modes, where it treats each chapter, section, etc., as a
+definition.  (@xref{Xref}, for a more powerful feature that handles
+multiple files together.)
 
 @findex imenu
 @vindex imenu-flatten
   If you type @kbd{M-g i} (@code{imenu}), it reads the name of a
 definition using the minibuffer, then moves point to that definition.
-You can use completion to specify the name; the command always
-displays the whole list of valid names.  If you set @code{imenu-flatten}
-to a non-@code{nil} value, then instead of the nested menu
-you can select a completion candidate from the flat list.
+You can use completion to specify the name; the command displays the
+list of matching valid names in the completions buffer.  If the index is
+hierarchical, then by default the completion candidates are also shown
+hierarchically, as a nested list: first you need to choose a section,
+then a subsection, etc., and finally the name of the definition.
+However, if you set @code{imenu-flatten} to a non-@code{nil} value, then
+instead of the nested menu you can select a completion candidate from a
+flattened list of definitions.  How the sections and subsections are
+shown in the flattened list of completion candidates depends on the
+value of @code{imenu-flatten}, which can be one of the following:
+
+@table @code
+@vindex imenu-level-separator
+@item prefix
+This shows each candidate prefixed by names of its section, subsection,
+subsubsection, etc., with each level separated from the next by the
+string that is the value of @code{imenu-level-separator}, by default
+@samp{:}.
+
+@item annotation
+This shows the section names as annotations, following each definition
+name.
+
+@item group
+This shows the completion candidates grouped by their sections.
+@end table
 
 @findex imenu-add-menubar-index
   Alternatively, you can bind the command @code{imenu} to a mouse
diff --git a/etc/NEWS b/etc/NEWS
index d8d55494128..9416ced5a0d 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1059,8 +1059,8 @@ point is not in a comment or a string.  It is by default bound to
 
 +++
 *** New user option 'imenu-flatten'.
-It defines whether to flatten the list of sections in an imenu
-or show it nested.
+It controls  whether to flatten the list of sections in an imenu, and
+how to display the sections in the flattened list.
 
 +++
 *** The sort order of Imenu completions can now be customized.
diff --git a/lisp/imenu.el b/lisp/imenu.el
index 3aec32fa708..708a39a0f71 100644
--- a/lisp/imenu.el
+++ b/lisp/imenu.el
@@ -151,18 +151,22 @@ Used for flattening nested indexes with name concatenation."
 (defcustom imenu-flatten nil
   "Whether to flatten the list of sections in an imenu or show it nested.
 If nil, use nested indexes.
-If `prefix', pop up the completion buffer with a flattened menu
-where section names are used as a prefix.
-If `annotation', use completion annotation as a suffix
-to append section names after the index names.
-If `group', split completions into groups.
-
-The string from `imenu-level-separator' is used to separate names of
-nested levels while flattening nested indexes with name concatenation."
-  :type '(choice (const :tag "Nested" nil)
-                 (const :tag "By prefix" prefix)
-                 (const :tag "By annotation" annotation)
-                 (const :tag "By group" group))
+If the value is `prefix', pop up the completion buffer with a
+flattened menu where section names are prepended to completion
+candidates as prefixes.
+If the value is `annotation', annotate each completion candidate
+with a suffix that is the section name to which it belongs.
+If the value is `group', split completion candidates into groups
+according to the sections.
+Any other value is treated as `prefix'.
+
+The value of `imenu-level-separator', a string, is used to separate
+names from different flattened levels, such as section names, from the
+names of completion candidates."
+  :type '(choice (const :tag "Show nested list" nil)
+                 (const :tag "Flat list with sections as prefix" prefix)
+                 (const :tag "Flat list annotated with sections" annotation)
+                 (const :tag "Flat list grouped by sections" group))
   :version "30.1")
 
 (defcustom imenu-generic-skip-comments-and-strings t