completing-read() with explanations of the possible alternatives

[Nordlöw <per.nordlow@gmail.com>]

Hi there!

I would like to extend completing-read() and completing-read-
multiple() in such a way that I get extra help for the alternatives
that are provided in the TABLE argument.

I thought that completing-read() would give this functionality by
default as the documentation for it says:
        "TABLE is an alist whose elements' cars are strings, or an
obarray."
I thought that the car was what displayed during completing-read() and
its corresponding cdr's were gathered in the return value.

But I only return the cars of these elements. Is it meant to be this
way? Should I perform the lookup of crds by using the return value of
completing-read(). If so how do I accomplish that for the different
possible TABLE types.

Example:
I want the interface for my completing-read-function to list the
alternatives something like this (preferrablly with vector or list in
font-lock-type-face and explanations in font-lock-comment-face)
- vector - Vector Container is ...
- list - List Container is ...
and return for example in the form
'("vector")

Thanks in advance,
Nordlöw