Completion with help

Question

I'm using completing-read to get an argument for an interactive command. The argument is a non-intuitive word (required for my application), so the completion list looks like this:

Possible completions are:
faz   foo   bar   baz

I'd like it to also show some help, something like this:

Possible completions are:
faz   Pogo quote part 2
foo   Regular fubar
bar   All the soap
baz   Pogo quote part 1

Is there a straight-forward way to accomplish this, or something similar?

Answer 1

I don't know about "straight-forward", but you can do it as follows:

(let* ((comps '(("faz" "Pogo quote part 2")
                ("foo" "Regular fubar")
                ...))
       (completion-extra-properties
        `(:annotation-function
          ,(lambda (s) (format "  %s" (cadr (assoc s comps)))))))
  (completing-read "Prompt: " comps))