GNU bug report logs - #49843
28.0.50; Error in docstring after using define-globalized-minor-mode

Previous Next

Full log

Message #11 received at 49843 <at> debbugs.gnu.org (full text, mbox):

From: Phil Sainty <psainty <at> orcon.net.nz>
To: dalanicolai <at> gmail.com
Cc: 49843 <at> debbugs.gnu.org
Subject: Re: bug#49843: 28.0.50; Error in docstring after using
 define-globalized-minor-mode
Date: Tue, 03 Aug 2021 21:18:18 +1200

In fact I was looking in Emacs 27, and it's all changed in 28,
so apologies for my confusion.  We actually now have this template:

(defconst easy-mmode--arg-docstring
  "

This is a minor mode.  If called interactively, toggle the `%s'
mode.  If the prefix argument is positive, enable the mode, and
if it is zero or negative, disable the mode.

If called from Lisp, toggle the mode if ARG is `toggle'.
Enable the mode if ARG is nil, omitted, or is a positive number.
Disable the mode if ARG is a negative number.

To check whether the minor mode is enabled in the current buffer,
evaluate `%S'.

The mode's hook is called both when the mode is enabled and when
it is disabled.")


That description still doesn't specify what happens with other
values, and I realise you're saying that the docstring of
`define-minor-mode' itself has a different, more comprehensive
explanation:

"When called from Lisp, the mode command toggles the mode if the
argument is `toggle', disables the mode if the argument is a
non-positive integer, and enables the mode otherwise (including
if the argument is omitted or nil or a positive integer)."

https://debbugs.gnu.org/cgi/bugreport.cgi?bug=44341 is related.

I notice the commit message for 5cea77af41b59ba6f6386264812c36ec31ba2efc
says:

    * lisp/emacs-lisp/easy-mmode.el (easy-mmode--arg-docstring):
    Only document the values we want to support, not the ones we
    actually support.

So the failure to say what happens if you pass something other
than an integer or 'toggle seems intentional, as other kinds of
argument shouldn't ever be used.

I expect that globalized modes should also use the text of the
`easy-mmode--arg-docstring' template.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.