master ba20b68d55: ; Improve documentation of 'imenu-flush-cache'

[Eli Zaretskii]

branch: master
commit ba20b68d558e67fe72cb47398e4decf261c45d7a
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; 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)
---
 doc/emacs/programs.texi | 13 +++++++++----
 etc/NEWS                |  2 ++
 lisp/imenu.el           |  4 +++-
 3 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 45bc4c79b4..2b27d4e13c 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 cf2ae19ce7..258fa499b7 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 e452b1bb8b..a08c58f682 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"))