bug#21644: 24.4; completing-read acts differently on functional collection

[Eli Zaretskii]

> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Fri, 16 Oct 2015 00:07:40 +0300
> Cc: 21644@debbugs.gnu.org
> 
> On 10/15/2015 11:28 PM, Drew Adams wrote:
> 
> > No one has said anything that would introduce another bug.
> > It's about fixing this bug, by getting users to the information
> > about function-valued COLLECTION.  And that info is in node
> > `Programmed Completion'.
> >
> > No one has said that users should not consult `Basic Completion'
> > for info about `all-completions', `try-completion', and
> > `test-completion'.
> 
> The current sentence that refers to the Info node would become wrong. 
> But I suppose an alternative wording might escape that problem.
> 
> Patch welcome.

Done.

> > Really what should be done is to link from the `completing-read'
> > doc string only to node `Minibuffer Completion', which is the
> > node that documents `completing-read'.
> 
> I don't know about that: that page basically re-tells the docstring of 
> completing-read. Sending to it from that docstring seems redundant.

I agree.

> > It is a bug (IMHO) that the node that documents `completing-read'
> > does not specify parameter COLLECTION - which is arguably the
> > *most important* parameter.
> 
> You're probably right. Please send a patch.

Done.

I also re-added the references to the completion functions into the
doc string of completing-read (and added 2 more functions to that
list).  While referencing the manual is good, especially for complex
topics, I feel that the absolute minimum of usage information,
including the arguments with which callbacks can be called, should be
available from the doc strings.