Make 'completion-preview-sort-function' a defcustom

* lisp/completion-preview.el
(completion-preview-sort-function): Define and document it
as a user option.
* etc/NEWS: Announce.

(cherry picked from commit 8b9194ae03214dd5169bd84f7d83bbe660dd9f90)

diff --git a/lisp/completion-preview.el b/lisp/completion-preview.el
index 68a898921a60e35bb572ff35d06346c3cc34aef1..6ace3f736d195725c7784132c454eee0ed57047e 100644 (file)
--- a/lisp/completion-preview.el
+++ b/lisp/completion-preview.el
@@ -236,8 +236,20 @@ affect the background color, for example with `hl-line-mode'."
                  (const :tag "Disable" nil))
   :version "31.1")
 
-(defvar completion-preview-sort-function #'minibuffer--sort-by-length-alpha
-  "Sort function to use for choosing a completion candidate to preview.")
+(defcustom completion-preview-sort-function #'minibuffer--sort-by-length-alpha
+  "Sort function to use for choosing a completion candidate to preview.
+
+Completion Preview mode calls the function that this option specifies to
+sort completion candidates.  The function takes one argument, the list
+of candidates, and returns the list sorted.
+
+The default sort function sorts first by length, then alphabetically.
+To disable sorting, set this option to `identity'.
+
+If the completion table that produces the candidates already specifies a
+sort function, it takes precedence over this option."
+  :type 'function
+  :version "31.1")
 
 (defface completion-preview
   '((t :inherit shadow))