GNU bug report logs - #10754
define-minor-mode and doc of derived mode

Previous Next

Full log

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

From: Stefan Monnier <monnier <at> IRO.UMontreal.CA>
To: John Shahid <jvshahid <at> gmail.com>
Cc: Eli Zaretskii <eliz <at> gnu.org>, drew.adams <at> oracle.com, 10754 <at> debbugs.gnu.org
Subject: Re: bug#10754: define-minor-mode and doc of derived mode
Date: Mon, 18 Jun 2018 09:47:30 -0400

>> I think we can avoid it by looking for the presence of ARG in
>> the docstring
> I think this can work, but it doesn't feel very elegant or obvious from
> the pov of the caller of `define-minor-mode'.  What's wrong with adding
> an extra keyword arg ?

I think in the long term (asymptotically), the arg is unneeded.
But if we add the arg, the long term will be that *all* calls will use
the arg, so we'll never be able to get rid of it.

I'd be OK with an arg of the form :dont-add-arg-paragraph (for those
hypothetical cases where the paragraph is undesirable) but not
:add-arg-paragraph.

>> (or by simply always adding it, and then going through
>> the various minor modes and remove the corresponding text from their
>> docstrings).
> I think this change needs to be backward compatible.  There could be
> other callers that aren't packaged with Emacs.

Having the same text twice in the output of `C-h f` is fairly harmless
in my opinion.  We've had similar situations where `C-h v` automatically
adds text like "this is only for interactive use" even tho the docstring
may already say it.


        Stefan

Previous Next

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