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:

>> From: Matt Armstrong <matt@rfc20.org>
>> Date: Tue, 30 Nov 2021 11:18:05 -0800
>> 
>> Attached is a docstring patch against the emacs-28 branch for this
>> issue.
>
> Thanks, but ... all these changes just to say that a list of strings
> can also be a COLLECTION?  This looks like a complete rewrite, and
> comparing it with the existing doc string is a lot of work.  Is the
> current doc string really that awful and requires such a complete
> rewrite?  Why can't we get away with a smaller, simpler change (that
> would be easier to review and approve)?

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.

Then I realized that the lisp reference manual is in good shape.  This
patch copies text almost verbatim from it.  So, the diff is both large
but hopefully not hard to verify in review.

Another issue is that these function provide extension points that pass
COLLECTION or elements from it directly to caller-supplied functions.
To write those functions correctly the programmer has to know all the
details of how the default C implementation works if the callbacks are
to work in a robust way.  In other words, this docstring is for
completion extension implementers as much as it is for callers.  I
figure an exhaustively pedantic approach is justifiable here.

One problem is the semantic complexity of how these functions interpret
COLLECTION.  They defy a simple and concise explanation.

E.g. COLLECTION can be...

 ...a list of strings
 ...a list of symbols
 ...an alist whose keys are strings
 ...an alist whose keys are symbols
 ...a list whose elements are a mixture of any of the above four
    possibilities.

And we have hash tables whose keys are strings, symbols, or a mix...

Also, any PREDICATE is passed the list elements (or hash key/values)
directly, without any symbol->string normalization.

Little of this is clear from the current docstrings, but the lisp ref
does a good job with it.


>> Note/question: I wonder if the `all-completions' docstring should refer
>> to `try-completion' rather than copy much of the text.  The same
>> approach works well in the lisp ref manual, I think.
>
> ELisp manual describes both one next to the other, so it can get away
> with such a technique.  Doc strings don't have that luxury; referring
> the user to another complex doc string generally raises the bar and
> makes the documentation harder to use, because one needs to constantly
> go back to the original function to figure out how the arguments
> described in the other function are used in the original one.  It's
> annoying.

That makes sense, thanks.