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

[Drew Adams <drew.adams@oracle.com>]

Let's just say that the doc string is incomplete and can easily
mislead.

If it says anything about interactive behavior (and it should)
then it should say just what the description of `define-minor-mode'
says for minor modes.

If it says anything about the behavior when called from
Lisp (and it should) then it should say just what the d-m-m
description says. This (i.e., _all_ of the d-m-m description)
is missing from the d-s-m doc string:

* `toggle' toggles
* non-positive integer disables
* anything else enables

The only bit of info you get about Lisp behavior is that
nil/absent enables - part of the "anything else".

Yes, the doc string does not say that (d-s-m t) disables.
But a cursory reading of this:

 "If called from Lisp, enable the mode if ARG is omitted or nil."

can give that impression.  Sure, it says "if" and not "only if",
but we all know that may people will understand "only if" or
"if and only if".

[And you can see that explicitly in the thread of bug #25435:
after reading such a description the filer thought it implied
that passing `off' should turn it off.  To which the snarky
reply was to belittle the filer's sense telling him:

 "Surely common sense tells you that is the intended meaning?
  There are about 130 instances of this form in Emacs.
  There are 4 instances of ", also enable", maybe you prefer
  that?
  Feel feel to correct them all, I guess, if it bothers you
  that much. :)"]

And as I said in the thread for bug #13926:

 "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."

It is also misleading for the doc string to talk about ARG
as if it were the prefix arg.

Right away that is going to feed confusion: absence of a
prefix arg toggles, but in Lisp absence of ARG enables.

Rather than the doc making clear the difference between
prefix arg interactively and ARG from Lisp, it seems to go
out of its way to confuse the two, saying "With a prefix ARG"
instead of "With a prefix arg" (or better, "prefix argument").
Better still would be to name the parameter something else
than ARG, to avoid just such confusion.

The behavior of minor-mode arguments is complex enough,
without bad doc to confuse things further.

It really should be clear by now that clearer doc is needed
about the behavior of minor-mode arguments (and there
continue to be questions and confusions about on reddit,
stackexchange, etc.).  How hard is it get this right now,
especially when writing new doc strings?

The point is that there is no reason to say anything
different for this than what is true for all minor modes
and what is said in the doc for d-m-m.

No, a user of a minor-mode function should not need to read
the doc of d-m-m to obtain info about its behavior.

Yes, each command should have a doc string that describes
its behavior: (1) interactively and (2) via Lisp.  (And if
a command is not intended for use from Lisp then that should
be stated explicitly.)

Do I think that it would be sufficient for every command
defined with d-m-m to have a link to the doc string of
d-m-m?  It would be OK, I think.  But barring that, each
minor-mode doc string needs to stand on its own and provide
that same info - not something partial or misleading.