bug#18202: 24.4.50; doc string of `next-error-buffer-p'

[Lars Ingebrigtsen <larsi@gnus.org>]

Drew Adams <drew.adams@oracle.com> writes:

> The doc string:
>
>  Test if BUFFER is a `next-error' capable buffer.
>
>  If AVOID-CURRENT is non-nil, treat the current buffer
>  as an absolute last resort only.
>
>  The function EXTRA-TEST-INCLUSIVE, if non-nil, is called in each buffer
>  that normally would not qualify.  If it returns t, the buffer
>  in question is treated as usable.
>
>  The function EXTRA-TEST-EXCLUSIVE, if non-nil, is called in each buffer
>  that would normally be considered usable.  If it returns nil,
>  that buffer is rejected.
>
> The doc string is very poor.
>
> 1. The first line should say that the predicate returns non-nil if
>    BUFFER is a `next-error'-capable buffer.

Fixed.

> 2. The doc string should then give some indication of what that means
>    (what it means for a buffer to be `next-error'-capable).

Hm...  No I think that's pretty evident.  It's a buffer in which the
command `next-error' makes sense.

> 3. The description of AVOID-CURRENT says nothing.  It needs to say what
>    the behavior is and how it affects the return value (if it does).
>    "Treat the buffer" means nothing here, as does "as a last resort."

Yes, that's odd.  Looking at the code, it just means that it returns nil
if given and BUFFER is the current buffer.  Fixed.

> 4. The other two paragraphs: What does it mean (a) for a buffer to
>    "qualify" or "normally be considered usable" ("normally"?  What does
>    that mean here?), and (b) for a buffer to be "usable" or "rejected"?
>    Again, this text says nothing helpful.  It should say what the
>    behavior is.
>
>    Presumably, the last sentence in each of these paragraphs should say
>    "If it returns [t|nil] then so does `next-error-buffer-p'."

Fixed.

> There really is nothing good about this doc string.  

It's an almost verbatim copy of the doc string from
`next-error-find-buffer', which explains why it's so odd.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no