Subject: bug#52202: [PATCH] try-completion, all-completions support for a list of strings COLLECTION is not documented in their docstrings

From: Eli Zaretskii <[email-masked]>
Date: Tue, 30 Nov 2021 21:30:20 +0200

> From: Matt Armstrong <[email-masked]>
> 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)?

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