From mboxrd@z Thu Jan  1 00:00:00 1970
Path: news.gmane.org!not-for-mail
From: Lars Ingebrigtsen <larsi@gnus.org>
Newsgroups: gmane.emacs.bugs
Subject: bug#18202: 24.4.50; doc string of `next-error-buffer-p'
Date: Sat, 30 Apr 2016 02:02:03 +0200
Message-ID: <8737q4klqc.fsf@gnus.org>
References: <f980a263-d7b2-4091-bf07-f12fe5509859@default>
NNTP-Posting-Host: plane.gmane.org
Mime-Version: 1.0
Content-Type: text/plain
X-Trace: ger.gmane.org 1461974631 32607 80.91.229.3 (30 Apr 2016 00:03:51 GMT)
X-Complaints-To: usenet@ger.gmane.org
NNTP-Posting-Date: Sat, 30 Apr 2016 00:03:51 +0000 (UTC)
Cc: 18202@debbugs.gnu.org
To: Drew Adams <drew.adams@oracle.com>
Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Apr 30 02:03:39 2016
Return-path: <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org>
Envelope-to: geb-bug-gnu-emacs@m.gmane.org
Original-Received: from lists.gnu.org ([208.118.235.17])
	by plane.gmane.org with esmtp (Exim 4.69)
	(envelope-from <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org>)
	id 1awINn-0005ZK-AS
	for geb-bug-gnu-emacs@m.gmane.org; Sat, 30 Apr 2016 02:03:39 +0200
Original-Received: from localhost ([::1]:56841 helo=lists.gnu.org)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org>)
	id 1awINj-0005c2-Dz
	for geb-bug-gnu-emacs@m.gmane.org; Fri, 29 Apr 2016 20:03:35 -0400
Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:39087)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1awINU-0005Cr-83
	for bug-gnu-emacs@gnu.org; Fri, 29 Apr 2016 20:03:33 -0400
Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1awINI-00039f-Eu
	for bug-gnu-emacs@gnu.org; Fri, 29 Apr 2016 20:03:14 -0400
Original-Received: from debbugs.gnu.org ([208.118.235.43]:43872)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1awINI-00035W-CC
	for bug-gnu-emacs@gnu.org; Fri, 29 Apr 2016 20:03:08 -0400
Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1awINC-00073r-1v
	for bug-gnu-emacs@gnu.org; Fri, 29 Apr 2016 20:03:02 -0400
X-Loop: help-debbugs@gnu.org
Resent-From: Lars Ingebrigtsen <larsi@gnus.org>
Original-Sender: "Debbugs-submit" <debbugs-submit-bounces@debbugs.gnu.org>
Resent-CC: bug-gnu-emacs@gnu.org
Resent-Date: Sat, 30 Apr 2016 00:03:02 +0000
Resent-Message-ID: <handler.18202.B18202.146197452927067@debbugs.gnu.org>
Resent-Sender: help-debbugs@gnu.org
X-GNU-PR-Message: followup 18202
X-GNU-PR-Package: emacs
X-GNU-PR-Keywords: 
Original-Received: via spool by 18202-submit@debbugs.gnu.org id=B18202.146197452927067
	(code B ref 18202); Sat, 30 Apr 2016 00:03:02 +0000
Original-Received: (at 18202) by debbugs.gnu.org; 30 Apr 2016 00:02:09 +0000
Original-Received: from localhost ([127.0.0.1]:56206 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces@debbugs.gnu.org>)
	id 1awIMK-00072T-Qy
	for submit@debbugs.gnu.org; Fri, 29 Apr 2016 20:02:09 -0400
Original-Received: from hermes.netfonds.no ([80.91.224.195]:52123)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <larsi@gnus.org>) id 1awIMI-00072L-MZ
	for 18202@debbugs.gnu.org; Fri, 29 Apr 2016 20:02:07 -0400
Original-Received: from cm-84.215.1.64.getinternet.no ([84.215.1.64] helo=mouse)
	by hermes.netfonds.no with esmtpsa
	(TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128)
	(Exim 4.84_2) (envelope-from <larsi@gnus.org>)
	id 1awIMF-0004ai-Jj; Sat, 30 Apr 2016 02:02:05 +0200
In-Reply-To: <f980a263-d7b2-4091-bf07-f12fe5509859@default> (Drew Adams's
	message of "Tue, 5 Aug 2014 12:52:03 -0700 (PDT)")
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1.50 (gnu/linux)
X-BeenThere: debbugs-submit@debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic]
X-Received-From: 208.118.235.43
X-BeenThere: bug-gnu-emacs@gnu.org
List-Id: "Bug reports for GNU Emacs,
	the Swiss army knife of text editors" <bug-gnu-emacs.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/bug-gnu-emacs>,
	<mailto:bug-gnu-emacs-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/bug-gnu-emacs/>
List-Post: <mailto:bug-gnu-emacs@gnu.org>
List-Help: <mailto:bug-gnu-emacs-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/bug-gnu-emacs>,
	<mailto:bug-gnu-emacs-request@gnu.org?subject=subscribe>
Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org
Original-Sender: "bug-gnu-emacs"
	<bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org>
Xref: news.gmane.org gmane.emacs.bugs:117300
Archived-At: <http://permalink.gmane.org/gmane.emacs.bugs/117300>

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