bug#15506: 24.3; checkdoc docstrings "non-nil"

[Lars Ingebrigtsen]

Kevin Ryde <user42@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@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