From 1a3b70e2d0e5acfebecbfd8cb7e963e3a0192263 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Wed, 19 Mar 2025 21:24:56 +0100
Subject: [PATCH] ; Improve documentation of incf and decf

* doc/lispref/variables.texi (Setting Generalized Variables): Mention
incf and decf.
* lisp/emacs-lisp/gv.el (incf, decf): Add references to Info manual
documentation on generalized variables.

(cherry picked from commit 03053baebee8a89f1b1d470a6173b9f1e80f0b39)
---
 doc/lispref/variables.texi |  4 ++++
 lisp/emacs-lisp/gv.el      | 10 ++++++++--
 2 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 75042237ab2..209b2b92c5f 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -2920,6 +2920,10 @@ the list stored in @var{place}.  It is analogous to @code{(setf
 subforms.  Note that @code{push} and @code{pop} on an @code{nthcdr}
 place can be used to insert or delete at any position in a list.
 
+Similarly, the macros @code{incf} and @code{decf} (@pxref{Arithmetic
+Operations}) can be used to increment or decrement generalized
+variables that are numbers.
+
 The @file{cl-lib} library defines various extensions for generalized
 variables, including additional @code{setf} places.
 @xref{Generalized Variables,,, cl, Common Lisp Extensions}.
diff --git a/lisp/emacs-lisp/gv.el b/lisp/emacs-lisp/gv.el
index a12fd166644..d133dd0e426 100644
--- a/lisp/emacs-lisp/gv.el
+++ b/lisp/emacs-lisp/gv.el
@@ -317,11 +317,14 @@ The return value is the last VAL in the list.
 
 ;;;###autoload
 (defmacro incf (place &optional delta)
-  "Increment PLACE by DELTA (default to 1).
+  "Increment generalized variable PLACE by DELTA (default to 1).
 
 The DELTA is first added to PLACE, and then stored in PLACE.
 Return the incremented value of PLACE.
 
+For more information about generalized variables, see Info node
+`(elisp) Generalized Variables'.
+
 See also `decf'."
   (declare (debug (gv-place &optional form)))
   (gv-letplace (getter setter) place
@@ -329,11 +332,14 @@ See also `decf'."
 
 ;;;###autoload
 (defmacro decf (place &optional delta)
-  "Decrement PLACE by DELTA (default to 1).
+  "Decrement generalized variable PLACE by DELTA (default to 1).
 
 The DELTA is first subtracted from PLACE, and then stored in PLACE.
 Return the decremented value of PLACE.
 
+For more information about generalized variables, see Info node
+`(elisp) Generalized Variables'.
+
 See also `incf'."
   (declare (debug (gv-place &optional form)))
   (gv-letplace (getter setter) place
-- 
2.39.5