Improve documentation of 'inhibit-modification-hooks' and friends

* src/buffer.c (Fset_buffer_modified_p)
(Frestore_buffer_modified_p): Doc fixes.
* src/insdel.c (syms_of_insdel) <inhibit-modification-hooks>:
Document in the doc string that this variable also inhibits file
locks and active region handling.  (Bug#29846)

2 files changed, 14 insertions, 3 deletions

diff --git a/src/buffer.c b/src/buffer.c
index 7ae889decf7..bcde2c80989 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -1320,7 +1320,12 @@ menu bar menus and the frame title.  */)
 DEFUN ("set-buffer-modified-p", Fset_buffer_modified_p, Sset_buffer_modified_p,
        1, 1, 0,
        doc: /* Mark current buffer as modified or unmodified according to FLAG.
-A non-nil FLAG means mark the buffer modified.  */)
+A non-nil FLAG means mark the buffer modified.
+In addition, this function unconditionally forces redisplay of the
+mode lines of the windows that display the current buffer, and also
+locks or unlocks the file visited by the buffer, depending on whether
+the function's argument is non-nil, but only if both `buffer-file-name'
+and `buffer-file-truename' are non-nil.  */)
   (Lisp_Object flag)
 {
   Frestore_buffer_modified_p (flag);
@@ -1341,7 +1346,10 @@ A non-nil FLAG means mark the buffer modified.  */)
 
 DEFUN ("restore-buffer-modified-p", Frestore_buffer_modified_p,
        Srestore_buffer_modified_p, 1, 1, 0,
-       doc: /* Like `set-buffer-modified-p', with a difference concerning redisplay.
+       doc: /* Like `set-buffer-modified-p', but doesn't redisplay buffer's mode line.
+This function also locks and unlocks the file visited by the buffer,
+if both `buffer-file-truename' and `buffer-file-name' are non-nil.
+
 It is not ensured that mode lines will be updated to show the modified
 state of the current buffer.  Use with care.  */)
   (Lisp_Object flag)
diff --git a/src/insdel.c b/src/insdel.c
index 5dfc62843a7..078f455eaaa 100644
--- a/src/insdel.c
+++ b/src/insdel.c
@@ -2342,7 +2342,10 @@ syms_of_insdel (void)
   DEFVAR_BOOL ("inhibit-modification-hooks", inhibit_modification_hooks,
                doc: /* Non-nil means don't run any of the hooks that respond to buffer changes.
 This affects `before-change-functions' and `after-change-functions',
-as well as hooks attached to text properties and overlays.  */);
+as well as hooks attached to text properties and overlays.
+Setting this variable non-nil also inhibits file locks and checks
+whether files are locked by another Emacs session, as well as
+handling of the active region per `select-active-regions'.  */);
   inhibit_modification_hooks = 0;
   DEFSYM (Qinhibit_modification_hooks, "inhibit-modification-hooks");