GNU bug report logs - #13926
24.3.50; doc string of `visual-line-mode'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 13926 in the body.
You can then email your comments to 13926 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.3.50; doc string of `visual-line-mode'
Date: Mon, 11 Mar 2013 13:19:30 -0700

The doc string is misleading wrt the argument when called from Lisp.
 
 With a prefix argument ARG, enable Visual Line mode if ARG is
 positive, and disable it otherwise.  If called from Lisp, enable
 the mode if ARG is omitted or nil.
 
This makes no connection between the interactive prefix arg and the arg
when called from Lisp.  In particular, it can also give the incorrect
impression that the mode is enabled ONLY if ARG is omitted or nil.
There is nothing that suggests the behavior of a non-positive or
positive ARG when called from Lisp.
 
By way of contrast, the doc string of `define-minor-mode' correctly says
what the argument values do when called from Lisp:
 
 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).
 
This kind of careful description should probably be added automatically
to functions defined by `define-minor-mode', to prevent misleading doc
wrt the argument.

In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2013-03-04 on ODIEONE
Bzr revision: 111935 yamaoka <at> jpl.org-20130304102733-4qy111z41qwoh2as
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -IC:/Devel/emacs/build/include --ldflags -LC:/Devel/emacs/build/lib'
 

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 13926 <at> debbugs.gnu.org
Subject: Re: bug#13926: 24.3.50; doc string of `visual-line-mode'
Date: Sat, 08 Feb 2014 04:58:32 -0800

"Drew Adams" <drew.adams <at> oracle.com> writes:

> The doc string is misleading wrt the argument when called from Lisp.
>
>  With a prefix argument ARG, enable Visual Line mode if ARG is
>  positive, and disable it otherwise.  If called from Lisp, enable
>  the mode if ARG is omitted or nil.
>
> This makes no connection between the interactive prefix arg and the arg
> when called from Lisp.  In particular, it can also give the incorrect
> impression that the mode is enabled ONLY if ARG is omitted or nil.
> There is nothing that suggests the behavior of a non-positive or
> positive ARG when called from Lisp.
>
> By way of contrast, the doc string of `define-minor-mode' correctly says
> what the argument values do when called from Lisp:
>
>  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).
>
> This kind of careful description should probably be added automatically
> to functions defined by `define-minor-mode', to prevent misleading doc
> wrt the argument.

Everything defined by `define-minor-mode' follows this model, I think?
Should `define-minor-mode' just append that to the function doc strings
automatically, and then we can remove the half-assed ARG explanations
from all the callers?

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

Previous Next

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