[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#15506: 24.3; checkdoc docstrings "non-nil"
From: |
Lars Ingebrigtsen |
Subject: |
bug#15506: 24.3; checkdoc docstrings "non-nil" |
Date: |
Wed, 24 Feb 2016 15:05:11 +1100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/25.1.50 (gnu/linux) |
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
- bug#15506: 24.3; checkdoc docstrings "non-nil",
Lars Ingebrigtsen <=