Clarify the behavior of minor mode commands

See Bug#24706.

* doc/lispref/modes.texi (Minor Mode Conventions): Clarify behavior when
the argument to a minor mode command is not an integer.
* lisp/emacs-lisp/easy-mmode.el (define-minor-mode): Clarify behavior
when ARG is not an integer.
* test/lisp/emacs-lisp/easy-mmode-tests.el: New file with unit tests.

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 368d882a4b86525eb9249e08807ee3c7cf887af0..ac0e95ec4ebd16954fee7a254457431c94dbd909 100644 (file)
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -1368,10 +1368,10 @@ called interactively with a prefix argument, it should enable the mode
 if the argument is positive and disable it otherwise.
 
 If the mode command is called from Lisp (i.e., non-interactively), it
-should enable the mode if the argument is omitted or @code{nil}; it
-should toggle the mode if the argument is the symbol @code{toggle};
-otherwise it should treat the argument in the same way as for an
-interactive call with a numeric prefix argument, as described above.
+should toggle the mode if the argument is the symbol @code{toggle}; it
+should disable the mode if the argument is a non-positive integer;
+otherwise, e.g., if the argument is omitted or nil or a positive
+integer, it should enable the mode.
 
 The following example shows how to implement this behavior (it is
 similar to the code generated by the @code{define-minor-mode} macro):

diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el
index 38295c302eacbba81c2a356857a7784fd46a2c26..64ef11457aa6f036c6486186150185e6b0e6df94 100644 (file)
--- a/lisp/emacs-lisp/easy-mmode.el
+++ b/lisp/emacs-lisp/easy-mmode.el
@@ -273,8 +273,12 @@ or call the function `%s'."))))
         ,(or doc
              (format (concat "Toggle %s on or off.
 With a prefix argument ARG, enable %s if ARG is
-positive, and disable it otherwise.  If called from Lisp, enable
-the mode if ARG is omitted or nil, and toggle it if ARG is `toggle'.
+positive, and disable it otherwise.
+
+When called from Lisp, toggle the mode if ARG is `toggle',
+disable the mode if ARG is a non-positive integer, and enable the
+mode otherwise (including if ARG is omitted or nil or a positive
+integer).
 \\{%s}") pretty-name pretty-name keymap-sym))
         ;; Use `toggle' rather than (if ,mode 0 1) so that using
         ;; repeat-command still does the toggling correctly.

diff --git a/test/lisp/emacs-lisp/easy-mmode-tests.el b/test/lisp/emacs-lisp/easy-mmode-tests.el
new file mode 100644 (file)
index 0000000..2593462
--- /dev/null
+++ b/test/lisp/emacs-lisp/easy-mmode-tests.el
@@ -0,0 +1,69 @@
+;;; easy-mmode-tests.el --- tests for easy-mmode.el  -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2016  Free Software Foundation, Inc.
+
+;; Author: Philipp Stephani <phst@google.com>
+
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; GNU Emacs is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; Unit tests for lisp/emacs-lisp/easy-mmode.el.
+
+;;; Code:
+
+(define-minor-mode easy-mmode-tests--mode nil)
+
+(ert-deftest easy-mmode-tests--modefun-nil ()
+  (let (easy-mmode-tests--mode)
+    (easy-mmode-tests--mode)
+    (should easy-mmode-tests--mode)))
+
+(ert-deftest easy-mmode-tests--modefun-0 ()
+  (let ((easy-mmode-tests--mode nil))
+    (easy-mmode-tests--mode)
+    (easy-mmode-tests--mode 0)
+    (should-not easy-mmode-tests--mode)))
+
+(ert-deftest easy-mmode-tests--modefun-+1 ()
+  (let ((easy-mmode-tests--mode nil))
+    (easy-mmode-tests--mode 1)
+    (should easy-mmode-tests--mode)))
+
+(ert-deftest easy-mmode-tests--modefun--1 ()
+  (let ((easy-mmode-tests--mode nil))
+    (easy-mmode-tests--mode)
+    (easy-mmode-tests--mode -1)
+    (should-not easy-mmode-tests--mode)))
+
+(ert-deftest easy-mmode-tests--modefun-toggle ()
+  (let ((easy-mmode-tests--mode nil))
+    (easy-mmode-tests--mode 'toggle)
+    (should easy-mmode-tests--mode)
+    (easy-mmode-tests--mode 'toggle)
+    (should-not easy-mmode-tests--mode)))
+
+(ert-deftest easy-mmode-tests--modefun-off ()
+  (let ((easy-mmode-tests--mode nil))
+    (easy-mmode-tests--mode 'off)
+    (should easy-mmode-tests--mode)))
+
+(ert-deftest easy-mmode-tests--modefun-t ()
+  (let ((easy-mmode-tests--mode nil))
+    (easy-mmode-tests--mode t)
+    (should easy-mmode-tests--mode)))
+
+;;; easy-mmode-tests.el ends here