bug#25428: 25.1; Incorrect doc string for `delete-selection-mode'

[nljlistbox2@gmail.com (N. Jackson)]

At 07:24 -0800 on Thursday 2017-01-12, Drew Adams wrote:

> The doc string says this:
>
>   If called from Lisp, enable the mode if ARG is omitted or nil.
>
> That is completely wrong. This is an ordinary minor mode,
> defined using `define-minor-mode', whose doc string says this:
>
>   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).

Hi Drew,

I do not see any contradiction between these two statements. Maybe
one of us is misreading them?

In particular, I find that the behaviour of
`delete-selection-mode' (the function) when called from Lisp
matches both statements in every particular, so I don't see what
you mean by "completely wrong".

> E.g., `(delete-selection-mode t)' ENABLES the mode, even though the
> `delete-selection-mode' doc string says that it DISABLES it.

Yes, this enables the mode, but no, the doc string does *not* say
this disables it. (In fact, it is silent on how to disable it from
Lisp.)

Am I missing something?

Admittedly, the part of its doc string that says how to use the
`delete-selection-mode' function from Lisp seems inadequate: It
doesn't say how to toggle the mode, it doesn't say how to disable
the mode, and the methods it mentions for enabling the mode do not
include the most straightforward one (passing it `t').

[Temporary minor rant: Personally it seems absurd to me that a
`nil' argument doesn't turn a minor mode off; and that calling the
minor mode function with no argument doesn't toggle it. But that
is all history of course.]

Anyway, does it make sense to re-document the canonical behaviour
of minor mode commands in the doc string of every minor mode
command?

Maybe it would be better (as I think you might have suggested in
another bug report back in January) if the doc string of the each
minor mode command had a link to the documentation of the
canonical behaviour.

N.