Subject: Re: bug#10754: define-minor-mode and doc of derived mode

From: Stefan Monnier <[email-masked]>
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