Subject: bug#76199: 30.0.93; completing-read-multiple is not documented in the manual

From: Daniel Mendler <[email-masked]>
Date: Tue, 11 Feb 2025 15:01:45 +0100

Eli Zaretskii <[email-masked]> writes:

>> From: Daniel Mendler <[email-masked]>
>> Cc: [email-masked]
>> Date: Tue, 11 Feb 2025 14:37:56 +0100
>> 
>> Eli Zaretskii <[email-masked]> writes:
>> 
>> >> Date: Tue, 11 Feb 2025 11:25:24 +0100
>> >> From:  Daniel Mendler via "Bug reports for GNU Emacs,
>> >>  the Swiss army knife of text editors" <[email-masked]>
>> >> 
>> >> Since documentation came up in bug#76028, it seems that
>> >> `completing-read-multiple' is not documented in the Elisp
>> >> manual, in particular in doc/lispref/minibuf.texi.
>> >
>> > We don't necessarily document every function.  Is this one important
>> > enough to be in the manual?
>> 
>> I think so.
>
> Can you tell why?

It is sometimes useful to complete multiple strings and
`completing-read-multiple' is a good tool to do that. So it may be
helpful to tell developers about this function. Alternatively one can
use `completing-read' in a loop, which I have also seen multiple times
in the Emacs code base or external packages.

> We could also compromise: mention the function's existence in the
> manual, but leave out its description (if that will just repeat what's
> in the doc string, it's just redundant).

This sounds like a good compromise. A short notice mentioning
`completing-read-multiple' below the documentation of `completing-read'
should suffice.

Daniel