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

[Eli Zaretskii <eliz@gnu.org>]

> Date: Sat, 9 Mar 2019 09:43:40 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 34794@debbugs.gnu.org
> 
> > > AFAICT neither the doc string nor the Elisp manual states what the
> > > default value is if argument DEF is nil.  IOW, what is the default
> > > buffer name if no explicit default is provided?  It seems (without
> > > thorough testing) to be the value of `(buffer-name (current-buffer))'.
> > 
> > No, it's an empty string, and I think the doc string already conveys
> > that.
> 
> I cannot tell from the doc string that the default value,
> i.e., the value returned when DEF is nil, is the empty
> string.

  Optional second arg DEF is value to return if user enters an empty line.

Doesn't this say that when DEF is omitted the function will return
that empty line?

> > (Note that if read-buffer-function is non-nil, what happens
> > then is entirely up to that function, which doesn't make it easy to
> > say exactly how DEF is handled.)
> 
> It's not hard to state what the default DEF behavior
> is, and then later say that if `read-buffer-function'
> is non-nil then the use of the other args is up to it,
> i.e., not necessarily as described above.  This is
> not unusual for a function that optionally accepts a
> function arg as one possibility.

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.