From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Kevin Ryde Newsgroups: gmane.emacs.bugs Subject: bug#15506: 24.3; checkdoc docstrings "non-nil" Date: Wed, 02 Oct 2013 14:16:44 +1000 Message-ID: <87d2noux1v.fsf@blah.blah> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Trace: ger.gmane.org 1380687558 3039 80.91.229.3 (2 Oct 2013 04:19:18 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Wed, 2 Oct 2013 04:19:18 +0000 (UTC) To: 15506@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Wed Oct 02 06:19:20 2013 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 1VRDuC-00081x-0N for geb-bug-gnu-emacs@m.gmane.org; Wed, 02 Oct 2013 06:19:20 +0200 Original-Received: from localhost ([::1]:33824 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VRDuB-0006kC-Jt for geb-bug-gnu-emacs@m.gmane.org; Wed, 02 Oct 2013 00:19:19 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:51208) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VRDu1-0006k5-Ks for bug-gnu-emacs@gnu.org; Wed, 02 Oct 2013 00:19:16 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VRDtu-00065M-GA for bug-gnu-emacs@gnu.org; Wed, 02 Oct 2013 00:19:09 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:40176) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VRDtu-00065I-Ch for bug-gnu-emacs@gnu.org; Wed, 02 Oct 2013 00:19:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1VRDtu-0006w2-2c for bug-gnu-emacs@gnu.org; Wed, 02 Oct 2013 00:19:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Kevin Ryde Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 02 Oct 2013 04:19:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 15506 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.138068752726636 (code B ref -1); Wed, 02 Oct 2013 04:19:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 2 Oct 2013 04:18:47 +0000 Original-Received: from localhost ([127.0.0.1]:48469 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1VRDte-0006vX-H7 for submit@debbugs.gnu.org; Wed, 02 Oct 2013 00:18:46 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:49462) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1VRDtc-0006vO-9x for submit@debbugs.gnu.org; Wed, 02 Oct 2013 00:18:45 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VRDtU-00063U-Ns for submit@debbugs.gnu.org; Wed, 02 Oct 2013 00:18:43 -0400 Original-Received: from lists.gnu.org ([2001:4830:134:3::11]:52265) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VRDtU-00063P-KR for submit@debbugs.gnu.org; Wed, 02 Oct 2013 00:18:36 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:51182) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VRDtO-0006i4-DA for bug-gnu-emacs@gnu.org; Wed, 02 Oct 2013 00:18:36 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VRDtI-00062a-7Q for bug-gnu-emacs@gnu.org; Wed, 02 Oct 2013 00:18:30 -0400 Original-Received: from mailout2-4.pacific.net.au ([61.8.2.227]:50237 helo=mailout4-syd3.pacific.net.au) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VRDtH-00062C-LP for bug-gnu-emacs@gnu.org; Wed, 02 Oct 2013 00:18:24 -0400 Original-Received: from blah.blah (unknown [1.147.110.15]) by mailout4-syd3.pacific.net.au (Postfix) with ESMTPA id 3FA6F4585DA for ; Wed, 2 Oct 2013 14:18:15 +1000 (EST) Original-Received: from gg by blah.blah with local (Exim 4.80) (envelope-from ) id 1VRDrg-0000to-30 for bug-gnu-emacs@gnu.org; Wed, 02 Oct 2013 14:16:44 +1000 User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.3 (gnu/linux) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 140.186.70.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:78860 Archived-At: --=-=-= Content-Type: text/plain Severity: wishlist Tags: patch 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 ...". 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". --=-=-= Content-Type: text/x-diff Content-Disposition: attachment; filename=checkdoc.el.non-nil.diff --- 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 --=-=-= Content-Type: text/plain 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 --=-=-=--