Add documentation about sorting Imenu completions (bug#70846)

* doc/emacs/programs.texi (Imenu): Document how Imenu completions
can be sorted.

* lisp/imenu.el (imenu-sort-function): Explain in the docstring
how to sort Imenu completions.

diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 01a1462044c84ca405a83e0a90cc5ffe289bee0a..8ab5033795dc6dd18d7681b9fd7f09a781488f5f 100644 (file)
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -378,6 +378,10 @@ they occur in the buffer; if you want alphabetic sorting, use the
 symbol @code{imenu--sort-by-name} as the value.  You can also
 define your own comparison function by writing Lisp code.
 
+  You can also customize how Imenu completions are sorted by changing
+the variable @code{completion-category-overrides} and setting its
+@code{display-sort-function} for the category @code{imenu}.
+
   If Eglot is activated for the current buffer's project
 (@pxref{Projects}) and the current buffer's major mode, Eglot provides
 its own facility for producing the buffer's index based on the

diff --git a/etc/NEWS b/etc/NEWS
index 5ecc385fa5b42ba64f092a4bc68b4bd46035961e..7b429414a7f2a8706a9890110cdc4e0c44a0592a 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1046,6 +1046,11 @@ point is not in a comment or a string.  It is by default bound to
 It defines whether to flatten the list of sections in an imenu
 or show it nested.
 
++++
+*** Imenu completions now can be sorted.
+You can customize the option 'completion-category-overrides'
+and set 'display-sort-function' for the category 'imenu'.
+
 ** Which Function mode
 
 +++

diff --git a/lisp/imenu.el b/lisp/imenu.el
index 2b1d4f5ce8546273c09f8e11d31b2f9dc1e38dfd..ea097f5da3a59dd1fa63c8a98dec4f76abbccc56 100644 (file)
--- a/lisp/imenu.el
+++ b/lisp/imenu.el
@@ -115,7 +115,10 @@ Useful things to use here include `reposition-window', `recenter', and
 (defcustom imenu-sort-function nil
   "The function to use for sorting the index mouse-menu.
 
-Affects only the mouse index menu.
+Affects only the mouse index menu.  If you want to change
+the sorting order of completions, you can customize
+the option `completion-category-overrides' and set
+`display-sort-function' for the category `imenu'.
 
 Set this to nil if you don't want any sorting (faster).
 The items in the menu are then presented in the order they were found