From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Lars Ingebrigtsen Newsgroups: gmane.emacs.bugs Subject: bug#15506: 24.3; checkdoc docstrings "non-nil" Date: Wed, 24 Feb 2016 15:05:11 +1100 Message-ID: <874mcykb2g.fsf@gnus.org> References: <87d2noux1v.fsf@blah.blah> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1456286781 16716 80.91.229.3 (24 Feb 2016 04:06:21 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Wed, 24 Feb 2016 04:06:21 +0000 (UTC) Cc: 15506@debbugs.gnu.org To: Kevin Ryde Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Wed Feb 24 05:06:13 2016 Return-path: 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 ) id 1aYQiJ-0006gi-9N for geb-bug-gnu-emacs@m.gmane.org; Wed, 24 Feb 2016 05:06:11 +0100 Original-Received: from localhost ([::1]:33375 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aYQiI-00005v-Kz for geb-bug-gnu-emacs@m.gmane.org; Tue, 23 Feb 2016 23:06:10 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:44823) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aYQiE-0008WN-06 for bug-gnu-emacs@gnu.org; Tue, 23 Feb 2016 23:06:07 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aYQiA-0004Um-Nf for bug-gnu-emacs@gnu.org; Tue, 23 Feb 2016 23:06:05 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:44984) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aYQiA-0004Ui-Ji for bug-gnu-emacs@gnu.org; Tue, 23 Feb 2016 23:06:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84) (envelope-from ) id 1aYQiA-0003fZ-9q for bug-gnu-emacs@gnu.org; Tue, 23 Feb 2016 23:06:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Lars Ingebrigtsen Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 24 Feb 2016 04:06:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 15506 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 15506-submit@debbugs.gnu.org id=B15506.145628674414079 (code B ref 15506); Wed, 24 Feb 2016 04:06:02 +0000 Original-Received: (at 15506) by debbugs.gnu.org; 24 Feb 2016 04:05:44 +0000 Original-Received: from localhost ([127.0.0.1]:42111 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aYQhs-0003f1-7o for submit@debbugs.gnu.org; Tue, 23 Feb 2016 23:05:44 -0500 Original-Received: from hermes.netfonds.no ([80.91.224.195]:35489) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aYQhp-0003es-EZ for 15506@debbugs.gnu.org; Tue, 23 Feb 2016 23:05:42 -0500 Original-Received: from cpe-60-225-211-161.nsw.bigpond.net.au ([60.225.211.161] helo=mouse) by hermes.netfonds.no with esmtpsa (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.72) (envelope-from ) id 1aYQhP-00085H-NA; Wed, 24 Feb 2016 05:05:16 +0100 In-Reply-To: <87d2noux1v.fsf@blah.blah> (Kevin Ryde's message of "Wed, 02 Oct 2013 14:16:44 +1000") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1.50 (gnu/linux) X-MailScanner-ID: 1aYQhP-00085H-NA MailScanner-NULL-Check: 1456891516.5976@/WMeJ2vpd4XDAA0zMlH8GQ 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" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:113654 Archived-At: Kevin Ryde writes: > This is an idea to have checkdoc propose "non-nil" at the start of > docstrings, rather than "true". > > For variables this is per the last tip in "(elisp)Documentation Tips". > The functions bit extends on similar lines. > > Maybe the function form could report further variations, eg. `eventp' > starts "True if the argument ...". I think this makes sense. Any objections to applying? > 2013-10-02 Kevin Ryde > > * checkdoc.el (checkdoc-this-string-valid-engine): Docstrings for > variables "True...", and functions "Return true...", should usually be > "non-nil". > > --- checkdoc.el.orig 2013-10-02 14:03:04.000000000 +1000 > +++ checkdoc.el 2013-10-02 14:04:32.000000000 +1000 > @@ -1621,6 +1621,17 @@ > ;; * If a user option variable records a true-or-false > ;; condition, give it a name that ends in `-flag'. > > + ;; "True ..." should be "Non-nil ..." > + (if (looking-at "\"\\*?\\(True\\)\\b") > + (if (checkdoc-autofix-ask-replace > + (match-beginning 1) (match-end 1) > + "Say \"Non-nil\" instead of \"True\"? " > + "Non-nil") > + nil > + (checkdoc-create-error > + "\"True\" should usually be \"Non-nil\"" > + (match-beginning 1) (match-end 1)))) > + > ;; If the variable has -flag in the name, make sure > (if (and (string-match "-flag$" (car fp)) > (not (looking-at "\"\\*?Non-nil\\s-+means\\s-+"))) > @@ -1780,6 +1791,16 @@ > "Probably \"%s\" should be imperative \"%s\"" > original replace) > (match-beginning 1) (match-end 1)))))) > + ;; "Return true ..." should be "Return non-nil ..." > + (if (looking-at "\"Return \\(true\\)\\b") > + (if (checkdoc-autofix-ask-replace > + (match-beginning 1) (match-end 1) > + "Say \"non-nil\" instead of \"true\"? " > + "non-nil") > + nil > + (checkdoc-create-error > + "\"true\" should usually be \"non-nil\"" > + (match-beginning 1) (match-end 1)))) > ;; Done with functions > ))) > ;;* When a documentation string refers to a Lisp symbol, write it as > > In GNU Emacs 24.3.1 (i486-pc-linux-gnu, X toolkit, Xaw3d scroll bars) > of 2013-05-29 on blah.blah, modified by Debian > System Description: Debian GNU/Linux unstable (sid) > > Configured using: > `configure '--build' 'i486-linux-gnu' '--build' 'i486-linux-gnu' > '--prefix=/usr' '--sharedstatedir=/var/lib' '--libexecdir=/usr/lib' > '--localstatedir=/var/lib' '--infodir=/usr/share/info' > '--mandir=/usr/share/man' '--with-pop=yes' > '--enable-locallisppath=/etc/emacs24:/etc/emacs:/usr/local/share/emacs/24.3/site-lisp:/usr/local/share/emacs/site-lisp:/usr/share/emacs/24.3/site-lisp:/usr/share/emacs/site-lisp' > '--with-crt-dir=/usr/lib/i386-linux-gnu' '--with-x=yes' > '--with-x-toolkit=lucid' '--with-toolkit-scroll-bars' '--without-gconf' > 'build_alias=i486-linux-gnu' 'CFLAGS=-g -O2 -fstack-protector > --param=ssp-buffer-size=4 -Wformat -Werror=format-security -Wall' > 'LDFLAGS=-Wl,-z,relro -Wl,-znocombreloc' > 'CPPFLAGS=-D_FORTIFY_SOURCE=2'' > > Important settings: > value of $LANG: en_AU > locale-coding-system: iso-latin-1-unix > default enable-multibyte-characters: t > -- (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no