bug#52202: 29.0.50; try-completion, all-completions support for a list of strings COLLECTION is not documented in their docstrings

[Matt Armstrong]

Eli Zaretskii <eliz@gnu.org> writes:

>> Thanks Eli, I can sympathize with respect to the review difficulty, but
>> I couldn't find a simple edit that did a good job.  It is more than just
>> "list of strings", but I did not realize when I filed the bug.  This
>> became clear only after I started reading code and trying to document
>> the current behavior.
>
> Can you list the aspects which the current doc string doesn't
> describe, or describes inaccurately or incorrectly?

Good question; maybe I went overboard.  Quotes below are from the
current docstring:

> If COLLECTION is an alist, the keys (cars of elements) are the
> possible completions.  If an element is not a cons cell, then the
> element itself is the possible completion.

I find this confusing because "If COLLECTION is an alist" strongly leads
the reader away from the idea that "COLLECTION may also be a list of
symbols/strings."  So perhaps replace this paragraph with slightly
edited text from the manual:

     If COLLECTION is a list (or alist), the permissible completions are
     specified by the elements of the list, each of which should be
     either a string, or a cons cell whose CAR is either a string or a
     symbol.  If the list contains elements of any other type, those are
     ignored.

> The argument given to PREDICATE is the alist element or the symbol
> from the obarray.

I found this confusing too, for the same reason.

So how about:

    The argument given to PREDICATE is either a string, symbol or a cons
    cell (the CAR of which is a string or symbol) from the list (or
    alist), or a symbol (_not_ a symbol name) from the obarray.  If
    COLLECTION is a hash table, PREDICATE is called with two arguments,
    the string or symbol key and the associated value.

These two blurbs are slight edits from the elisp manual.  I think this
new wording would be good in both the doc string and the manual.

If these smaller edits seem good I'm happy to reformulate the patch (I
can update the manual as well).