Subject: bug#34073: 26.1; Missing documentation for minor mode hook behavior

From: Noam Postavsky <[email-masked]>
Date: Tue, 09 Jul 2019 18:35:57 -0400

Lars Ingebrigtsen <[email-masked]> writes:

> Piotr Kaznowski <[email-masked]> writes:
>
>> I couldn't find essential information about minor mode hooks behavior,
>> namely that "The minor mode's hook is called both when activating and
>> deactivating the minor mode" (as stated here:
>> https://emacs.stackexchange.com/a/47092/17425).
>>
>> It isn't mentioned in the manual (sections "Minor Modes" and "Hooks"),
>> nor in the docstring for `add-hook' function.
>
> Mentioning it `add-hook' is perhaps not natural, and I don't think it's
> 100% adhered to, anyway?  Only by minor modes that are defined by
> define-minor-mode?  Other minor modes may or may not call the hook.
>
> It is mentioned in the "Defining Minor Modes" node of the Lisp
> manual...  but is probably not where people would be looking for this
> information.
>
> Hm.  Perhaps `add-hook' is the right place to mention this anyway?  But
> with caveats about, well, everything?

Maybe define-minor-mode could mention this in the mode's docstring, like
it does for the ARG?