Changes to completing-read

[Phil Hagelberg <phil@hagelb.org>]

I've been building a couple tools that use the completing-read function
for more advanced completions, and I've got some questions about how it
behaves when a function is passed as the "collection" argument.

From the completing-read docstring:

> 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.

It looks like the function gets called four times when the user presses
TAB, and the only difference between the four calls is the last
argument. t, nil, 'lambda, and the cons (boundaries . "") are
passed. According to the docstrings of try-completion and
all-completions, t and nil should be passed to the collection function
when those two functions get called as part of the completion process
somehow. But I have no idea where 'lambda or (boundaries . "") are
coming from.

From the try-completion docstring:

> Return common substring of all completions of string in collection.
> Test each possible completion specified by collection
> to see if it begins with string.

From the all-completions docstring:

> Search for partial matches to string in collection.
> Test each of the possible completions specified by collection
> to see if it begins with string.

It's rather unclear from the docstrings, but from what I can piece
together, the "collection" function should act totally differently based
on the value of the third argument.

So it seems there are really three problems:

* The description overall behaviour of the "collection" function is spread
  out over three separate docstrings and is even then not very clear.

* One function (collection) is supposed to perform four distinct tasks
  based on the value of one of its arguments. (Though this is probably
  justified for backwards-compatibility reasons; seems fairly
  understandable.)

* Only two of the four tasks that the function is supposed to perform are
  documented at all.

Is this accurate? Could someone explain the meaning of the mystery
arguments? I would like to submit a documentation patch, but I feel that
my understanding of the subject is very sketchy, and the implementation
is in C, so I can't just dive in and understand it.

thanks,
Phil