completing-read, incomplete documentation for "programmed completion"

[Ulrich Mueller <ulm@gentoo.org>]

Hi,

I think that the documentation of `completing-read' should be
improved, with respect to "programmed completion". Currently, its
docstring says about the subject:

,----
| COLLECTION can also be a function to do the completion itself.
| PREDICATE limits completion to a subset of COLLECTION.
| See `try-completion' and `all-completions' for more details
|  on completion, COLLECTION, and PREDICATE.
`----

Now the docstrings of `try-completion' and `all-completions' (and
`test-completion', which is not mentioned for some reason) just say
that `nil', `t', or `lambda' will be passed as the third argument to
the completion function, respectively.

However, if I evaluate the following expression:
   (completing-read "Prompt: " 'debug)

and type TAB in the minibuffer, the debugger shows that neither `nil'
nor `t' nor `lambda' are passed, but that the third argument is
`(boundaries . "")'.

The debugger also shows that it is called by `completion-boundaries',
but the docstring of this function (which didn't exist in Emacs 22?)
is not helpful at all.

Am I missing something? IMHO, `completing-read' should explain its
COLLECTION argument, and should also explain what are the possible
arguments passed to the completion function.

(BTW, also the Elisp Reference Manual mentions only `nil', `t', and
`lambda' in section 20.6.6, "Programmed Completion".)

Ulrich