bug#13926: 24.3.50; doc string of `visual-line-mode'

[Lars Ingebrigtsen]

"Drew Adams" <drew.adams@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/