[PATCH 1/5] gdb/doc: improve Python Disassembler API documentation

Andrew Burgess via Gdb-patches
2023-04-04T08:21:38Z

Some small improvements to the Python Disassembler API documentation:

* More use of @var{...} in the @defun lines,

* Be consistent about using the package scope in the @deftp lines,

* Rework the description of the DisassemblerResult class to include
mention of builtin_disassemble.
---
gdb/doc/python.texi | 29 ++++++++++++++++++-----------
1 file changed, 18 insertions(+), 11 deletions(-)

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index c74d586ef39..a350260559f 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -6909,7 +6909,7 @@
@code{RuntimeError} exception if it is invalid.
@end defun

-@defun DisassembleInfo.__init__ (info)
+@defun DisassembleInfo.__init__ (@var{info})
This can be used to create a new @code{DisassembleInfo} object that is
a copy of @var{info}. The copy will have the same @code{address},
@code{architecture}, and @code{progspace} values as @var{info}, and
@@ -6923,7 +6923,7 @@
(@pxref{builtin_disassemble}).
@end defun

-@defun DisassembleInfo.read_memory (length, offset)
+@defun DisassembleInfo.read_memory (@var{length}, @var{offset})
This method allows the disassembler to read the bytes of the
instruction to be disassembled. The method reads @var{length} bytes,
starting at @var{offset} from
@@ -6973,16 +6973,17 @@
@end defun
@end deftp

-@deftp {class} Disassembler
+@anchor{Disassembler Class}
+@deftp {class} gdb.disassembler.Disassembler
This is a base class from which all user implemented disassemblers
must inherit.

-@defun Disassembler.__init__ (name)
+@defun Disassembler.__init__ (@var{name})
The constructor takes @var{name}, a string, which should be a short
name for this disassembler.
@end defun

-@defun Disassembler.__call__ (info)
+@defun Disassembler.__call__ (@var{info})
The @code{__call__} method must be overridden by sub-classes to
perform disassembly. Calling @code{__call__} on this base class will
raise a @code{NotImplementedError} exception.
@@ -7023,10 +7024,16 @@
@end defun
@end deftp

-@deftp {class} DisassemblerResult
-This class is used to hold the result of calling
-@w{@code{Disassembler.__call__}}, and represents a single disassembled
-instruction. This class has the following properties and methods:
+@deftp {class} gdb.disassembler.DisassemblerResult
+This class represents the result of disassembling a single
+instruction. An instance of this class will be returned from
+@code{builtin_disassemble} (@pxref{builtin_disassemble}), and an
+instance of this class should be returned from
+@w{@code{Disassembler.__call__}} (@pxref{Disassembler Class}) if an
+instruction was successfully disassembled.
+
+The @code{DisassemblerResult} class has the following properties and
+methods:

@defun DisassemblerResult.__init__ (@var{length}, @var{string})
Initialize an instance of this class, @var{length} is the length of
@@ -7049,7 +7056,7 @@
The following functions are also contained in the
@code{gdb.disassembler} module:

-@defun register_disassembler (disassembler, architecture)
+@defun register_disassembler (@var{disassembler}, @var{architecture})
The @var{disassembler} must be a sub-class of
@code{gdb.disassembler.Disassembler} or @code{None}.

@@ -7099,7 +7106,7 @@
@end defun

@anchor{builtin_disassemble}
-@defun builtin_disassemble (info)
+@defun builtin_disassemble (@var{info})
This function calls back into @value{GDBN}'s builtin disassembler to
disassemble the instruction identified by @var{info}, an instance, or
sub-class, of @code{DisassembleInfo}.
--
2.25.4