GNU bug report logs - #15506
24.3; checkdoc docstrings "non-nil"

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 15506 in the body.
You can then email your comments to 15506 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.3; checkdoc docstrings "non-nil"
Date: Wed, 02 Oct 2013 14:16:44 +1000

[Message part 1 (text/plain, inline)]

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  <user42 <at> zip.com.au>

	* checkdoc.el (checkdoc-this-string-valid-engine): Docstrings for
	variables "True...", and functions "Return true...", should usually be
	"non-nil".

[checkdoc.el.non-nil.diff (text/x-diff, attachment)]

[Message part 3 (text/plain, inline)]

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

Message #8 received at 15506 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Kevin Ryde <user42 <at> zip.com.au>
Cc: 15506 <at> debbugs.gnu.org
Subject: Re: bug#15506: 24.3; checkdoc docstrings "non-nil"
Date: Wed, 24 Feb 2016 15:05:11 +1100

Kevin Ryde <user42 <at> zip.com.au> 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  <user42 <at> zip.com.au>
>
> 	* 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

Message #11 received at 15506 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: user42 <at> zip.com.au, 15506 <at> debbugs.gnu.org
Subject: Re: bug#15506: 24.3; checkdoc docstrings "non-nil"
Date: Wed, 24 Feb 2016 19:16:12 +0200

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Date: Wed, 24 Feb 2016 15:05:11 +1100
> Cc: 15506 <at> debbugs.gnu.org
> 
> Kevin Ryde <user42 <at> zip.com.au> 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?

None here.

Message #14 received at 15506 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: user42 <at> zip.com.au, 15506 <at> debbugs.gnu.org
Subject: Re: bug#15506: 24.3; checkdoc docstrings "non-nil"
Date: Thu, 25 Feb 2016 16:16:55 +1030

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Lars Ingebrigtsen <larsi <at> gnus.org>
>> Date: Wed, 24 Feb 2016 15:05:11 +1100
>> Cc: 15506 <at> debbugs.gnu.org
>> 
>> Kevin Ryde <user42 <at> zip.com.au> 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?
>
> None here.

I've now applied this to the Emacs trunk.

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.