GNU bug report logs - #76199
30.0.93; completing-read-multiple is not documented in the manual

Previous Next

Full log

Message #23 received at 76199 <at> debbugs.gnu.org (full text, mbox):

From: Daniel Mendler <mail <at> daniel-mendler.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 76199 <at> debbugs.gnu.org
Subject: Re: bug#76199: 30.0.93; completing-read-multiple is not documented
 in the manual
Date: Tue, 11 Feb 2025 15:01:45 +0100

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Daniel Mendler <mail <at> daniel-mendler.de>
>> Cc: 76199 <at> debbugs.gnu.org
>> Date: Tue, 11 Feb 2025 14:37:56 +0100
>> 
>> Eli Zaretskii <eliz <at> gnu.org> 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" <bug-gnu-emacs <at> gnu.org>
>> >> 
>> >> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.