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

[Andrew Burgess <aburgess@redhat.com>]

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