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.

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

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
 
 +++

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