bug#34794: 26.1; doc of `read-buffer'

[Eli Zaretskii <eliz@gnu.org>]

> Date: Sat, 9 Mar 2019 14:32:22 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 34794@debbugs.gnu.org
> 
> > Please suggest such a text, because I definitely don't see an easy way
> > of saying that, without triggering more bug reports like this one.
> 
> 1. OK.  How about this?

Thanks, I used some ideas from your suggestion.

> 4. There appears to be a fairly large bug in the
> behavior, BTW.  The function is supposed to return a
> buffer name, which is presumably a string.
> 
> But try this, hitting `RET' with empty minibuffer input:
> 
>  (read-buffer "b: " (selected-window) t)
> 
> That returns a window!  And this returns a number, not
> a numeric string:
> 
>  (read-buffer "b: " 42 t)
> 
> It apparently can return anything at all.

AFAICT, it just behaves according to documentation of DEF.

> This is in spite of the fact that the REQUIRE-MATCH
> arg is `t', and according to the doc that should
> mean that you cannot exit the minibuffer unless the
> input corresponds to an existing buffer.

That's only valid for something the user types, AFAIU.

> Do you prefer a separate bug report for this bug, or
> can you fix it based on this report?

I don't really see what is there to fix.

> 5. Other doc-string bugs (fixed in my suggestion):
> 
> * Doesn't say that it reads with completion.  (You
>   can guess that, when you read some of the argument
>   descriptions - it mentions completion only in
>   passing.)
> * Doesn't say in what way REQUIRE-MATCH "determines
>   whether non-existing buffer names are allowed".
>   It refers to `completing-read', but that says
>   nothing about existing buffers - that says only
>   that WHATEVER the set of candidates, you cannot
>   exit the minibuffer without matching one of them.
> * Arguments are described out of order.
> * Arg PREDICATE is described after the statement
>   about `read-buffer-function'.

I believe I fixed all of these now.

Thanks.