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

Previous Next

Full log

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.