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