[3.8] bpo-15817: gdbinit: Document commands after defining them (GH-15021) (#15744)

The gdb manual[1] says the following for "document":

  The command commandname must already be defined.

[1] https://sourceware.org/gdb/current/onlinedocs/gdb/Define.html

And indeed when trying to use the gdbinit file with gdb 8.3, I get:

  .../cpython/Misc/gdbinit:17: Error in sourced command file:
  Undefined command: "pyo".  Try "help".

Fix this by moving all documentation blocks after the define blocks.

This was introduced in GH-6384.
(cherry picked from commit 1f86fdcfc57270ee569cc58269a4e08afe7608ec)

Authored-by: Florian Bruhin <me@the-compiler.org>

diff --git a/Misc/gdbinit b/Misc/gdbinit
index afefe0818e4c77abb6437cd1a54c2d2a19dae1d6..45e79fcf6f4682d1445be4f5a4a92da4ef3cddf9 100644 (file)
--- a/Misc/gdbinit
+++ b/Misc/gdbinit
@@ -14,30 +14,27 @@
 # with embedded macros that you may find superior to what is in here.
 # See Tools/gdb/libpython.py and http://bugs.python.org/issue8032.
 
-document pyo
-  Prints a representation of the object to stderr, along with the
-  number of reference counts it currently has and the hex address the
-  object is allocated at.  The argument must be a PyObject*
-end
 define pyo
     # side effect of calling _PyObject_Dump is to dump the object's
     # info - assigning just prevents gdb from printing the
     # NULL return value
     set $_unused_void = _PyObject_Dump($arg0)
 end
-
-document pyg
+document pyo
   Prints a representation of the object to stderr, along with the
   number of reference counts it currently has and the hex address the
-  object is allocated at.  The argument must be a PyGC_Head*
+  object is allocated at.  The argument must be a PyObject*
 end
+
 define pyg
     print _PyGC_Dump($arg0)
 end
-
-document pylocals
-  Print the local variables of the current frame.
+document pyg
+  Prints a representation of the object to stderr, along with the
+  number of reference counts it currently has and the hex address the
+  object is allocated at.  The argument must be a PyGC_Head*
 end
+
 define pylocals
     set $_i = 0
     while $_i < f->f_code->co_nlocals
@@ -50,6 +47,9 @@ define pylocals
         set $_i = $_i + 1
     end
 end
+document pylocals
+  Print the local variables of the current frame.
+end
 
 # A rewrite of the Python interpreter's line number calculator in GDB's
 # command language
@@ -75,13 +75,13 @@ define lineno
     printf "%d", $__li
 end
 
-document pyframev
-  Print the current frame - verbose
-end
 define pyframev
     pyframe
     pylocals
 end
+document pyframev
+  Print the current frame - verbose
+end
 
 define pyframe
     set $__fn = PyUnicode_AsUTF8(f->f_code->co_filename)
@@ -134,9 +134,6 @@ end
 # the interpreter you may will have to change the functions you compare with
 # $pc.
 
-document pystack
-  Print the entire Python call stack
-end
 define pystack
     while $pc < Py_Main || $pc > Py_GetArgcArgv
         if $pc > PyEval_EvalFrameEx && $pc < _PyEval_EvalFrameDefault
@@ -146,10 +143,10 @@ define pystack
     end
     select-frame 0
 end
-
-document pystackv
-  Print the entire Python call stack - verbose mode
+document pystack
+  Print the entire Python call stack
 end
+
 define pystackv
     while $pc < Py_Main || $pc > Py_GetArgcArgv
         if $pc > PyEval_EvalFrameEx && $pc < _PyEval_EvalFrameDefault
@@ -159,10 +156,10 @@ define pystackv
     end
     select-frame 0
 end
-
-document pu
-  Generally useful macro to print a Unicode string
+document pystackv
+  Print the entire Python call stack - verbose mode
 end
+
 def pu
   set $uni = $arg0
   set $i = 0
@@ -174,3 +171,6 @@ def pu
     end
   end
 end
+document pu
+  Generally useful macro to print a Unicode string
+end