From 22bf7158a5803aa98d5b580e5a00a6356343d90b Mon Sep 17 00:00:00 2001
From: Jeremy Bryant <jb@jeremybryant.net>
Date: Sat, 6 Dec 2025 23:03:21 +0000
Subject: [PATCH] ; * src/.gdbinit: Improve comments of .gdbinit helper
 functions (bug#79932)

xgetptr: Improve comment describing helper function.
xgetint: Add comment describing helper function.
xgettype: Add comment describing helper function.
xgetsym: Add comment describing helper function.
xprintstr: Add comment describing helper function.

Co-authored-by: Eli Zaretskii <eliz@gnu.org>
---
 src/.gdbinit | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/src/.gdbinit b/src/.gdbinit
index 673edaf9ec7..cf007c1f99e 100644
--- a/src/.gdbinit
+++ b/src/.gdbinit
@@ -50,6 +50,9 @@ if defined_HAVE_PGTK
   handle SIGPIPE nostop noprint
 end
 
+# Helper command to get the pointer to the C struct that holds the data
+# of a Lisp object given as argument, by removing the GC and type-tag bits.
+# Stores the result in $ptr.
 # Use $bugfix so that the value isn't a constant.
 # Using a constant runs into GDB bugs sometimes.
 define xgetptr
@@ -61,6 +64,8 @@ define xgetptr
   set $ptr = (EMACS_INT) $bugfix & VALMASK
 end
 
+# Helper command to extract the C integer value of a Lisp fixnum given as argument.
+# Stores the result in $int.
 define xgetint
   if (CHECK_LISP_OBJECT_TYPE)
     set $bugfix = $arg0.i
@@ -70,6 +75,9 @@ define xgetint
   set $int = (EMACS_INT) $bugfix << (USE_LSB_TAG ? 0 : INTTYPEBITS) >> INTTYPEBITS
 end
 
+# Helper command to produce the type of a Lisp_Object, given as argument,
+# as a value from the 'Lisp_Type' enumeration.
+# Stores the result in $type.
 define xgettype
   if (CHECK_LISP_OBJECT_TYPE)
     set $bugfix = $arg0.i
@@ -79,6 +87,9 @@ define xgettype
   set $type = (enum Lisp_Type) (USE_LSB_TAG ? (EMACS_INT) $bugfix & (1 << GCTYPEBITS) - 1 : (EMACS_UINT) $bugfix >> VALBITS)
 end
 
+# Helper command to get the pointer to 'struct Lisp_Symbol'
+# corresponding to the Lisp object given as argument.
+# Stores the result in $ptr.
 define xgetsym
   xgetptr $arg0
   set $ptr = ((struct Lisp_Symbol *) ((char *) &lispsym + $ptr))
@@ -1121,6 +1132,10 @@ document xpr
 Print $ as a lisp object of any type.
 end
 
+# Helper command to print the text of a Lisp string given as argument.
+# Stores the pointer to the C string data in $data and its length in
+# characters (excluding the terminating null) in $strsize.
+# Prints "0" for empty strings and strings longer than 1000 characters.
 define xprintstr
   if (! $arg0)
     output "DEAD"