bug#20462: 25.0.50; A minor mode's doc string should say it is [local/global] a minor mode

bug#20462: 25.0.50; A minor mode's doc string should say it is [local/global] a minor mode

[Drew Adams]

A minor mode created conventionally, i.e., using `define-minor-mode' or
`define-globalized-minor-mode', should automatically have its doc string
say explicitly that it is a minor mode and whether it is local or
global.

That helps users know what to expect, because all such minor modes have
some things in common, which are well documented.

In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2015-04-05 on LEG570
Bzr revision: 16eec6fc55dcc05d1d819f18998e84a9580b2521
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --host=i686-pc-mingw32 --enable-checking=yes,glyphs'

bug#20462: 25.0.50; A minor mode's doc string should say it is [local/global] a minor mode

[Glenn Morris]

(define-globalized-minor-mode foo auto-fill-mode 'ignore)

C-h foo

Toggle Auto-Fill mode in all buffers.

1) It's a minor mode (you can't toggle a major mode, nor sensibly apply
it to all buffers).
2) It's global ("all buffers").



(define-minor-mode blah nil)

C-f blah

Toggle Blah mode on or off.

1) It's a minor mode (you can't toggle a major mode)
2) Since it does not say it affects all buffers, don't assume it does.

bug#20462: 25.0.50; A minor mode's doc string should say it is [local/global] a minor mode

[Drew Adams]

> (define-globalized-minor-mode foo auto-fill-mode 'ignore)
> C-h foo
> Toggle Auto-Fill mode in all buffers.
> 
> 1) It's a minor mode (you can't toggle a major mode, nor sensibly
> apply it to all buffers).
> 2) It's global ("all buffers").
> (define-minor-mode blah nil)
> C-f blah
> Toggle Blah mode on or off.
> 1) It's a minor mode (you can't toggle a major mode)
> 2) Since it does not say it affects all buffers, don't assume it
> does.

Irrelevant to this bug report.  A command that toggles something,
including toggling a mode, is not necessarily a minor-mode command. 

See, for example, the misnamed `use-hard-newlines' command of
bug #20464.  It happens to be a minor-mode command.  But with
that name it might just as well not have been.  And there is
no way to tell from its doc string that it has anything to do
with a minor mode.  `define-globalized-minor-mode' and
`define-minor-mode' should explicitly add something to the
doc string to make clear that the command is not just some
command that toggles.  They should explicitly mention "minor mode".

bug#20462: 25.0.50; A minor mode's doc string should say it is [local/global] a minor mode

[Drew Adams]

> See, for example, the misnamed `use-hard-newlines' command of
> bug #20464.

I meant bug #20461, which is about the name.

bug#20462: 25.0.50; A minor mode's doc string should say it is [local/global] a minor mode

[Artur Malabarba]

2015-04-30 14:47 GMT+01:00 Drew Adams

>> (define-globalized-minor-mode foo auto-fill-mode 'ignore)
>> C-h foo
>> Toggle Auto-Fill mode in all buffers.
>>
>> 1) It's a minor mode (you can't toggle a major mode, nor sensibly
>> apply it to all buffers).
>> 2) It's global ("all buffers").
>> (define-minor-mode blah nil)
>> C-f blah
>> Toggle Blah mode on or off.
>> 1) It's a minor mode (you can't toggle a major mode)
>> 2) Since it does not say it affects all buffers, don't assume it
>> does.
>
> Irrelevant to this bug report.  A command that toggles something,
> including toggling a mode, is not necessarily a minor-mode command.

I agree with Drew here. The fact that this information can be inferred
(deciphered, perhaps) from the docstring doesn't mean that it
shouldn't be included explicitly. Even more so where it comes minor
modes, which are commands that even the most basic users will interact
with (and probably read).

bug#20462: 25.0.50; A minor mode's doc string should say it is [local/global] a minor mode

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> A minor mode created conventionally, i.e., using `define-minor-mode' or
> `define-globalized-minor-mode', should automatically have its doc string
> say explicitly that it is a minor mode and whether it is local or
> global.
>
> That helps users know what to expect, because all such minor modes have
> some things in common, which are well documented.

Yeah, I kinda think that `define-minor-mode' should include the toggle
verbiage by default at the start of all doc strings, even if there is a
doc string given.  That would mean going through all the usages in the
tree and remove the leading incantations, but that's no big deal.

We could have a keyword :no-introduction t for the few modes that really
don't want the standard verbiage at the start.

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

bug#20462: 25.0.50; A minor mode's doc string should say it is [local/global] a minor mode

[Drew Adams]

In addition, I think it would be good if the doc for the mode
either mentioned whether the mode is currently on or (at least)
mentioned the associated variable, letting users know that the
value of that variable will tell them whether it is currently
on or off.  (They might also need to be told that they need to
examine the variable value in the appropriate buffer.  Or else
clicking the variable link in the doc for the function should
evaluate it in the proper buffer (same buffer that the function
doc was invoked from).