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

Previous Next

Full log

Message #20 received at 20462 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 20462 <at> debbugs.gnu.org
Subject: Re: bug#20462: 25.0.50;
 A minor mode's doc string should say it is [local/global] a minor mode
Date: Sat, 30 Apr 2016 21:03:32 +0200

Drew Adams <drew.adams <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.