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

[Drew Adams <drew.adams@oracle.com>]

> > 1. OK.  How about this?
> Thanks, I used some ideas from your suggestion.

Thx.  Definitely better than what was there before
the bug report.  My (minor) feedback, FWIW:

1. It says that the return value is a string buffer
name.  That's generally, and probably expected to
be, the case.

But as we've seen, if DEF is not a string or a
list of strings then the default return value is
not a string.
	
It's an open question whether the doc should
discourage using non-string values with DEF.

If it should then the doc should do that.  If
it shouldn't then perhaps the doc should point
out that DEF can violate this expectation of a
string buffer name (GIGO).

2. "if user enters an empty line, instead of that
empty string" is unclear.

What empty string?  No empty string has been
mentioned, so "that" empty string doesn't mean
anything.  And what does "instead of" refer to?
Is the user entering an empty line somehow instead
of "that empty string"?  Unclear.

It should just say that empty input (not an empty
"line", BTW - minibuffer input isn't line-oriented)
means that the empty string is returned.

3. It should say which buffer names are completion
candidates (all live buffers, it seems).

This is different, for example, from the case of
`read-file-name', which excludes some file names
based on option `completion-ignored-extensions'.

Many buffers, especially those users interact with,
are visiting files, and it's not unreasonable to
suppose that `completion-ignored-extension' or
another, similar variable applies to `read-buffer'.
There is no such variable - users can only use
PREDICATE to exclude buffer names.

4. It's unclear that the `read-buffer-function'
value, when called, is passed all of the args to
`read-buffer', in order.