From: Lars Ingebrigtsen <larsi@gnus.org>
To: Kevin Ryde <user42@zip.com.au>
Cc: 15506@debbugs.gnu.org
Subject: bug#15506: 24.3; checkdoc docstrings "non-nil"
Date: Wed, 24 Feb 2016 15:05:11 +1100 [thread overview]
Message-ID: <874mcykb2g.fsf@gnus.org> (raw)
In-Reply-To: <87d2noux1v.fsf@blah.blah> (Kevin Ryde's message of "Wed, 02 Oct 2013 14:16:44 +1000")
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
next prev parent reply other threads:[~2016-02-24 4:05 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2013-10-02 4:16 bug#15506: 24.3; checkdoc docstrings "non-nil" Kevin Ryde
2016-02-24 4:05 ` Lars Ingebrigtsen [this message]
2016-02-24 17:16 ` Eli Zaretskii
2016-02-25 5:46 ` Lars Ingebrigtsen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=874mcykb2g.fsf@gnus.org \
--to=larsi@gnus.org \
--cc=15506@debbugs.gnu.org \
--cc=user42@zip.com.au \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.