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

Previous Next

Full log

View this message in rfc822 format

From: John Shahid <jvshahid <at> gmail.com>
To: Stefan Monnier <monnier <at> IRO.UMontreal.CA>
Cc: Eli Zaretskii <eliz <at> gnu.org>, drew.adams <at> oracle.com, 10754 <at> debbugs.gnu.org
Subject: bug#10754: define-minor-mode and doc of derived mode
Date: Wed, 20 Jun 2018 19:33:24 +0000

Stefan Monnier <monnier <at> IRO.UMontreal.CA> writes:

>>> 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'm worried about minor modes that don't even mention the argument. Not
sure if that should be a concern since they should be documenting the
ARG in the first place. I can provide examples, but the Emacs codebase
has a few of those.

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

Sounds good. I will make this change and reply with a patch.

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