* bug#15506: 24.3; checkdoc docstrings "non-nil"
@ 2013-10-02 4:16 Kevin Ryde
2016-02-24 4:05 ` Lars Ingebrigtsen
0 siblings, 1 reply; 4+ messages in thread
From: Kevin Ryde @ 2013-10-02 4:16 UTC (permalink / raw)
To: 15506
[-- Attachment #1: Type: text/plain, Size: 551 bytes --]
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@zip.com.au>
* checkdoc.el (checkdoc-this-string-valid-engine): Docstrings for
variables "True...", and functions "Return true...", should usually be
"non-nil".
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: checkdoc.el.non-nil.diff --]
[-- Type: text/x-diff, Size: 1680 bytes --]
--- 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
[-- Attachment #3: Type: text/plain, Size: 1068 bytes --]
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
^ permalink raw reply [flat|nested] 4+ messages in thread
* bug#15506: 24.3; checkdoc docstrings "non-nil"
2013-10-02 4:16 bug#15506: 24.3; checkdoc docstrings "non-nil" Kevin Ryde
@ 2016-02-24 4:05 ` Lars Ingebrigtsen
2016-02-24 17:16 ` Eli Zaretskii
0 siblings, 1 reply; 4+ messages in thread
From: Lars Ingebrigtsen @ 2016-02-24 4:05 UTC (permalink / raw)
To: Kevin Ryde; +Cc: 15506
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
^ permalink raw reply [flat|nested] 4+ messages in thread
* bug#15506: 24.3; checkdoc docstrings "non-nil"
2016-02-24 4:05 ` Lars Ingebrigtsen
@ 2016-02-24 17:16 ` Eli Zaretskii
2016-02-25 5:46 ` Lars Ingebrigtsen
0 siblings, 1 reply; 4+ messages in thread
From: Eli Zaretskii @ 2016-02-24 17:16 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: user42, 15506
> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Wed, 24 Feb 2016 15:05:11 +1100
> Cc: 15506@debbugs.gnu.org
>
> 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?
None here.
^ permalink raw reply [flat|nested] 4+ messages in thread
* bug#15506: 24.3; checkdoc docstrings "non-nil"
2016-02-24 17:16 ` Eli Zaretskii
@ 2016-02-25 5:46 ` Lars Ingebrigtsen
0 siblings, 0 replies; 4+ messages in thread
From: Lars Ingebrigtsen @ 2016-02-25 5:46 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: user42, 15506
Eli Zaretskii <eliz@gnu.org> writes:
>> From: Lars Ingebrigtsen <larsi@gnus.org>
>> Date: Wed, 24 Feb 2016 15:05:11 +1100
>> Cc: 15506@debbugs.gnu.org
>>
>> 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?
>
> 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
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2016-02-25 5:46 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2013-10-02 4:16 bug#15506: 24.3; checkdoc docstrings "non-nil" Kevin Ryde
2016-02-24 4:05 ` Lars Ingebrigtsen
2016-02-24 17:16 ` Eli Zaretskii
2016-02-25 5:46 ` Lars Ingebrigtsen
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).