From 82583ee3afbb1278e664a3e5858a93bc698c370b Mon Sep 17 00:00:00 2001
From: Daniel Mendler <mail@daniel-mendler.de>
Date: Sun, 25 Apr 2021 02:04:23 +0200
Subject: [PATCH] (affixation-function): Allow only three-element list elements

Restrict the definition of the `affixation-function`. The function
must return a list of three element lists. Since the
`affixation-function` is part of the widely used `completing-read` API
a simplification is helpful for both authors of completion UIs and
authors of completion tables.

* doc/lispref/minibuf.texi: Update documentation.
* lisp/minibuffer.el: Update documentation.
  (minibuffer-completion-help): Add assertion.
* lisp/simple.el (read-extended-command--affixation): Return
  three-element lists.
---
 doc/lispref/minibuf.texi | 10 ++++------
 lisp/minibuffer.el       | 22 ++++++++++++----------
 lisp/simple.el           |  7 +++++--
 3 files changed, 21 insertions(+), 18 deletions(-)

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 7cf2fcf68f..28d3afac22 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -1819,12 +1819,10 @@ Completion Variables
 @item :affixation-function
 The value should be a function to add prefixes and suffixes to
 completions.  This function must accept one argument, a list of
-completions, and should return such a list of completions where
-each element contains a list of three elements: a completion,
-a prefix string, and a suffix string.  When this function
-returns a list of two elements, it is interpreted as a list
-of a completion and a suffix string like in @code{:annotation-function}.
-This function takes priority over @code{:annotation-function}.
+completions, and should return a list of annotated completions.  Each
+element of the returned list must be a three-element list, the
+completion, a prefix string, and a suffix string.  This function takes
+priority over @code{:annotation-function}.
 
 @item :exit-function
 The value should be a function to run after performing completion.
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 98691c2ede..f76ce37030 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -122,10 +122,10 @@ completion-metadata
    returns a string to append to STRING.
 - `affixation-function': function to prepend/append a prefix/suffix to
    entries.  Takes one argument (COMPLETIONS) and should return a list
-   of completions with a list of either two elements: completion
-   and suffix, or three elements: completion, its prefix
-   and suffix.  This function takes priority over `annotation-function'
-   when both are provided, so only this function is used.
+   of annotated completions.  The elements of the list must be
+   three-element lists: completion, its prefix and suffix.  This
+   function takes priority over `annotation-function' when both are
+   provided, so only this function is used.
 - `display-sort-function': function to sort entries in *Completions*.
    Takes one argument (COMPLETIONS) and should return a new list
    of completions.  Can operate destructively.
@@ -1972,11 +1972,11 @@ completion-extra-properties
 
 `:affixation-function': Function to prepend/append a prefix/suffix to
    completions.  The function must accept one argument, a list of
-   completions, and return a list where each element is a list of
-   either two elements: a completion, and a suffix, or
-   three elements: a completion, a prefix and a suffix.
-   This function takes priority over `:annotation-function'
-   when both are provided, so only this function is used.
+   completions, and return a list of annotated completions.  The
+   elements of the list must be three-element lists: completion, its
+   prefix and suffix.  This function takes priority over
+   `:annotation-function' when both are provided, so only this
+   function is used.
 
 `:exit-function': Function to run after completion is performed.
 
@@ -2110,7 +2110,9 @@ minibuffer-completion-help
                       (cond
                        (aff-fun
                         (setq completions
-                              (funcall aff-fun completions)))
+                              (funcall aff-fun completions))
+                        (cl-assert (or (not completions)
+                                       (= 3 (length (car completions))))))
                        (ann-fun
                         (setq completions
                               (mapcar (lambda (s)
diff --git a/lisp/simple.el b/lisp/simple.el
index 999755a642..26eb8cad7f 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -2080,8 +2080,11 @@ read-extended-command--affixation
                             (obsolete
                              (format " (%s)" (car obsolete)))
                             ((and binding (not (stringp binding)))
-                             (format " (%s)" (key-description binding))))))
-         (if suffix (list command-name suffix) command-name)))
+                             (format " (%s)" (key-description binding)))
+                            (t ""))))
+         (put-text-property 0 (length suffix)
+                            'face 'completions-annotations suffix)
+         (list command-name "" suffix)))
      command-names)))
 
 (defcustom suggest-key-bindings t
-- 
2.20.1