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

[Kevin Ryde <user42@zip.com.au>]

[-- 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