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

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

[Piotr Kaznowski]

--text follows this line--

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.

Please consider adding this information in the relevant sections of the docs.
Thank you.

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

[Lars Ingebrigtsen]

Piotr Kaznowski <piotr.kaznowski@gmail.com> 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?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Noam Postavsky]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Piotr Kaznowski <piotr.kaznowski@gmail.com> 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?

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

[Lars Ingebrigtsen]

Noam Postavsky <npostavs@gmail.com> writes:

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

It subtly alludes to this in this bit:

--
BODY contains code to execute each time the mode is enabled or disabled.
  It is executed after toggling the mode, and before running MODE-hook.
--

But that's not the documentation somebody who wonders when hooks are run
would look -- that macro is for people who implement modes, not people
who just wants to run some hooks...

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Noam Postavsky]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Noam Postavsky <npostavs@gmail.com> writes:
>
>> Maybe define-minor-mode could mention this in the mode's docstring, like
>> it does for the ARG?
>
> It subtly alludes to this in this bit:
>
> --
> BODY contains code to execute each time the mode is enabled or disabled.
>   It is executed after toggling the mode, and before running MODE-hook.
> --

I didn't mean the docstring of define-minor-mode, I meant the docstring
of the mode it defines.

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

[Lars Ingebrigtsen]

Noam Postavsky <npostavs@gmail.com> writes:

> I didn't mean the docstring of define-minor-mode, I meant the docstring
> of the mode it defines.

Yes, that makes sense.  I just had a look at a random one of these:

---

auto-image-file-mode is an autoloaded interactive Lisp function in
‘image-file.el’.

(auto-image-file-mode &optional ARG)

  Probably introduced at or before Emacs version 21.1.

Toggle visiting of image files as images (Auto Image File mode).

If called interactively, enable Auto-Image-File mode if ARG is positive, and
disable it if ARG is zero or negative.  If called from Lisp,
also enable the mode if ARG is omitted or nil, and toggle it
if ARG is ‘toggle’; disable the mode otherwise.

An image file is one whose name has an extension in
‘image-file-name-extensions’, or matches a regexp in
‘image-file-name-regexps’.

---

It doesn't mention the hook at all...  which I guess it could do?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Noam Postavsky <npostavs@gmail.com> writes:
>
>> I didn't mean the docstring of define-minor-mode, I meant the docstring
>> of the mode it defines.
>
> Yes, that makes sense.  I just had a look at a random one of these:

[...]

> It doesn't mention the hook at all...  which I guess it could do?

I've now added a sentence to easy-mmode--arg-docstring.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no