Subject: bug#55451: 28.1.50; Executing (jit-lock-mode -1) does not disable jit-lock-mode

From: Ihor Radchenko <[email-masked]>
Date: Fri, 20 May 2022 16:13:58 +0800

Eli Zaretskii <[email-masked]> writes:

>> That's exactly the situation I had:
>> 1. Tried M-x jit-lock-mode. Did not work. Understandable - special minor
>>    mode.
>> 2. M-: (jit-lock-mode -1). No error. Executed.
>> 3. Tried to debug something assuming that jit-lock is disabled.
>> 4. After several minutes, realised that jit-lock is still working.
>
> But the doc string already caters to your use case:
>
>   If you need to debug code run from jit-lock, see `jit-lock-debug-mode'

To clarify, I was trying to debug race condition in font-lock itself.
jit-lock made things even more complex and I just wanted to quickly
disable it. I did not want to debug jit-lock behaviour at all.

>> I would not expect users to read minor mode docstring every time to
>> check if the usual convention is broken.
>
> Users don't need to turn off jit-lock.  People who want to debug it,
> OTOH, _are_ expected to read the doc string.

I understand. I do not consider the described issue critical. However,
from a perspective of Elisp developer, minor mode docstrings rarely
contain low-level information. Rather general minor mode description +
standard boilerplate generated by define-minor-mode. That boilerplate is
well-known an is usually not worth checking out multiple times:

>>> This is a minor mode.  If called interactively, toggle the
>>> Org-Indent mode mode.  If the prefix argument is positive,
>>> enable the mode, and if it is zero or negative, disable the mode.
>>> 
>>> If called from Lisp, toggle the mode if ARG is toggle.  Enable
>>> the mode if ARG is nil, omitted, or is a positive number.
>>> Disable the mode if ARG is a negative number.
>>> 
>>> To check whether the minor mode is enabled in the current buffer,
>>> evaluate ...

So, I would not expect that habituated developers actually check out the
docstring regarding enabling/disabling the mode. At least I did not
until I realised that something is strange and jit-lock-mode was not
disabled after M-: (jit-lock-mode -1)

Again, it is just my perspective consisting of a single personal
datapoint. If you think that the current state is ok, feel free to
disregard my complaint.

Best,
Ihor