bug#49843: 28.0.50; Error in docstring after using define-globalized-minor-mode

bug#49843: 28.0.50; Error in docstring after using define-globalized-minor-mode

[dalanicolai]

When creating a global minor mode using `define-globalized-minor-mode',
some explanation in the default created docstring for the new global
minor mode reads (e.g. for `global-display-fill-column-indicator-mode')
:

"With prefix ARG, enable Global Display-Fill-Column-Indicator mode if
ARG is positive; otherwise, disable it.  If called from Lisp, enable
the mode if ARG is omitted or nil."

So it says that, when called from lisp, the mode is not enabled if any
ARG except nil is passed.

It is easy to verify that that statement is wrong by evaluating
(global-display-fill-column-indicator-mode
'with-any-non-negative-number-argument) directly after starting emacs
with -Q flag. Also the argument 'toggle can be uses for toggling it.

It looks like the docstring could just copy the explanation about
behavior when calling from lisp from the `define-minor-mode'
docstring. (I am not sure if the `define-globalized-minor-mode' macro
adds any logic for the behavior for (de)activating the global
mode; I think it only adds logic for the behavior i.c.w. its non-global
mode, for which the explanation is not clear to me also b.t.w., but I
am
still trying to track down how that behaves exactly).


In GNU Emacs 28.0.50 (build 1, x86_64-pc-linux-gnu, GTK+ Version
3.24.25, cairo version 1.16.0)
 of 2021-02-18 built on daniel-fedora
Repository revision: 185121da6978553d538d37d6d0e67dc52e13311f
Repository branch: feature/native-comp
Windowing system distributor 'The X.Org Foundation', version
11.0.12011000
System Description: Fedora 34 (Workstation Edition)

Configured using:
 'configure --with-nativecomp'

Configured features:
CAIRO DBUS FREETYPE GIF GLIB GMP GNUTLS GPM GSETTINGS HARFBUZZ JPEG
JSON
LCMS2 LIBOTF LIBSELINUX LIBSYSTEMD LIBXML2 M17N_FLT MODULES NATIVE_COMP
NOTIFY INOTIFY PDUMPER PNG RSVG SOUND THREADS TIFF TOOLKIT_SCROLL_BARS
X11 XDBE XIM XPM GTK3 ZLIB

Important settings:
  value of $LANG: en_US.UTF-8
  value of $XMODIFIERS: @im=none
  locale-coding-system: utf-8-unix

Major mode: Lisp Interaction

Minor modes in effect:
  global-display-fill-column-indicator-mode: t
  display-fill-column-indicator-mode: t
  tooltip-mode: t
  global-eldoc-mode: t
  eldoc-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t

Load-path shadows:
None found.

Features:
(shadow sort mail-extr emacsbug message rmc puny dired dired-loaddefs
rfc822 mml mml-sec epa derived epg epg-config gnus-util rmail
rmail-loaddefs auth-source cl-seq eieio eieio-core eieio-loaddefs
password-cache json map cl-macs text-property-search mm-decode mm-
bodies
mm-encode mail-parse rfc2231 mailabbrev gmm-utils mailheader sendmail
rfc2047 rfc2045 ietf-drums mm-util mail-prsvr mail-utils pp easy-mmode
display-fill-column-indicator time-date subr-x cl-extra seq byte-opt gv
bytecomp byte-compile cconv cl-print hl-line thingatpt help-fns
radix-tree help-mode easymenu cl-loaddefs cl-lib iso-transl tooltip
eldoc electric uniquify ediff-hook vc-hooks lisp-float-type mwheel
term/x-win x-win term/common-win x-dnd tool-bar dnd fontset image
regexp-opt fringe tabulated-list replace newcomment text-mode elisp-
mode
lisp-mode prog-mode register page tab-bar menu-bar rfn-eshadow isearch
timer select scroll-bar mouse jit-lock font-lock syntax facemenu
font-core term/tty-colors frame minibuffer cl-generic cham georgian
utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao korean
japanese eucjp-ms cp51932 hebrew greek romanian slovak czech european
ethiopic indian cyrillic chinese composite charscript charprop
case-table epa-hook jka-cmpr-hook help simple abbrev obarray
cl-preloaded nadvice button loaddefs faces cus-face pcase macroexp
files
window text-properties overlay sha1 md5 base64 format env code-pages
mule custom widget hashtable-print-readable backquote threads dbusbind
inotify lcms2 dynamic-setting system-font-setting font-render-setting
cairo move-toolbar gtk x-toolkit x multi-tty make-network-process
nativecomp emacs)

Memory information:
((conses 16 80391 7027)
 (symbols 48 7063 0)
 (strings 32 22435 1869)
 (string-bytes 1 727500)
 (vectors 16 13456)
 (vector-slots 8 294714 10744)
 (floats 8 35 31)
 (intervals 56 239 0)
 (buffers 992 12))

bug#49843: 28.0.50; Error in docstring after using define-globalized-minor-mode

[Phil Sainty]

On 2021-08-03 16:51, dalanicolai@gmail.com wrote:
> It looks like the docstring could just copy the explanation about
> behavior when calling from lisp from the `define-minor-mode'
> docstring.

I would use the more succinct explanation that `define-minor-mode'
generates (by default) for the docstring of the mode being defined.
E.g.:

"If called interactively, enable Eldoc mode if ARG is positive, and
disable it if ARG is zero or negative.  If called from Lisp, also
enable the mode if ARG is omitted or nil, and toggle it if ARG is
`toggle'; disable the mode otherwise."

This comes from the format variable `easy-mmode--arg-docstring'.


> (I am not sure if the `define-globalized-minor-mode' macro
> adds any logic for the behavior for (de)activating the global
> mode.

`define-globalized-minor-mode' uses `define-minor-mode' to define
the global mode, so there's no unusual behaviour.


> I think it only adds logic for the behavior i.c.w. its non-global
> mode, for which the explanation is not clear to me also b.t.w., but
> I am still trying to track down how that behaves exactly).

Which aspects are you unsure of?

bug#49843: 28.0.50; Error in docstring after using define-globalized-minor-mode

[Phil Sainty]

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.

bug#49843: 28.0.50; Error in docstring after using define-globalized-minor-mode

[Lars Ingebrigtsen]

Phil Sainty <psainty@orcon.net.nz> writes:

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

Yup.  Now done in Emacs 28.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no