; Improve documentation of 'imenu-flush-cache'

* etc/NEWS: Expand the description of 'imenu-flush-cache'.

* doc/emacs/programs.texi (Imenu): Document 'imenu-flush-cache'.

* lisp/imenu.el (imenu-flush-cache): Doc fix.  (Bug#20589)

3 files changed, 14 insertions, 5 deletions

diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 45bc4c79b4f..2b27d4e13c6 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -250,10 +250,10 @@ where it treats each chapter, section, etc., as a definition.
 together.)
 
 @findex imenu
-  If you type @kbd{M-g i}, 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 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.
 
 @findex imenu-add-menubar-index
   Alternatively, you can bind the command @code{imenu} to a mouse
@@ -280,6 +280,11 @@ changes in the text.
 than @code{imenu-auto-rescan-maxout} in bytes, and scanning is
 stopped if it takes more than @code{imenu-max-index-time} seconds.
 
+@findex imenu-flush-cache
+  You can force Imenu to forget the buffer's index with @w{@kbd{M-x
+imenu-flush-cache @key{RET}}}.  This causes Imenu to rescan the
+current buffer next time you invoke @kbd{M-g i} in that buffer.
+
 @vindex imenu-sort-function
   You can customize the way the menus are sorted by setting the
 variable @code{imenu-sort-function}.  By default, names are ordered as
diff --git a/etc/NEWS b/etc/NEWS
index cf2ae19ce73..258fa499b79 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -667,6 +667,8 @@ available options can be restored by enabling this option.
 
 ---
 *** New command 'imenu-flush-cache'.
+Use it if you want Imenu to forget the buffer's index alist and
+recreate it anew next time 'imenu' is invoked.
 
 * Editing Changes in Emacs 29.1
 
diff --git a/lisp/imenu.el b/lisp/imenu.el
index e452b1bb8b9..a08c58f6825 100644
--- a/lisp/imenu.el
+++ b/lisp/imenu.el
@@ -900,7 +900,9 @@ for more information."
       (_ (error "Unknown imenu item: %S" index-item)))))
 
 (defun imenu-flush-cache ()
-  "Flush the current imenu cache."
+  "Flush the current imenu cache.
+This forces a full rescan of the buffer to recreate the index alist
+next time `imenu' is invoked."
   (interactive)
   (setq imenu--index-alist nil)
   (message "Flushed the imenu cache"))