From 92bbe911e99968c04509c553767fa83bfdcbeb18 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Fri, 6 May 2022 15:15:27 +0300
Subject: [PATCH] ; Improve documentation of 'buffer-local-set-state'

* lisp/emacs-lisp/easy-mmode.el (buffer-local-set-state)
(buffer-local-restore-state): Doc fixes.

* doc/lispref/modes.texi (Defining Minor Modes): Fix a typo and
improve wording and indexing.
---
 doc/lispref/modes.texi        |  7 ++++---
 lisp/emacs-lisp/easy-mmode.el | 10 +++++-----
 2 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index bfd9724173b..a0c1c488fe7 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -1912,14 +1912,15 @@ This means ``use in modes derived from @code{text-mode}, but nowhere
 else''.  (There's an implicit @code{nil} element at the end.)
 @end defmac
 
+@findex buffer-local-restore-state
 @defmac buffer-local-set-state variable value...
-Minor modes often set buffer-local variables that alters some features
+Minor modes often set buffer-local variables that affect some features
 in Emacs.  When a minor mode is switched off, the mode is expected to
 restore the previous state of these variables.  This convenience macro
 helps with doing that: It works much like @code{setq-local}, but
 returns an object that can be used to restore these values back to
-their previous values/states (with the
-@code{buffer-local-restore-state} function).
+their previous values/states (using the companion function
+@code{buffer-local-restore-state}).
 @end defmac
 
 @node Mode Line Format
diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el
index bade14ec3d8..2568eaeb76a 100644
--- a/lisp/emacs-lisp/easy-mmode.el
+++ b/lisp/emacs-lisp/easy-mmode.el
@@ -827,9 +827,9 @@ Interactively, COUNT is the prefix numeric argument, and defaults to 1."
 
 
 (defmacro buffer-local-set-state (&rest pairs)
-  "Like `setq-local', but return an object that allows restoring previous state.
-Use `buffer-local-restore-state' on the returned object to
-restore the state.
+  "Like `setq-local', but allow restoring the previous state of locals later.
+This macro returns an object that can be passed to `buffer-local-restore-state'
+in order to restore the state of the local variables set via this macro.
 
 \(fn [VARIABLE VALUE]...)"
   (declare (debug setq))
@@ -854,8 +854,8 @@ restore the state.
 
 ;;;###autoload
 (defun buffer-local-restore-state (states)
-  "Restore buffer local variable values in STATES.
-STATES is an object returned by `buffer-local-set-state'."
+  "Restore values of buffer-local variables recorded in STATES.
+STATES should be an object returned by `buffer-local-set-state'."
   (pcase-dolist (`(,variable ,local ,value) states)
     (if local
         (set variable value)
-- 
2.39.5