[1/5] gdb/doc: improve Python Disassembler API documentation
Commit Message
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(-)
Comments
> Cc: Andrew Burgess <aburgess@redhat.com>
> Date: Tue, 4 Apr 2023 09:21:03 +0100
> From: Andrew Burgess via Gdb-patches <gdb-patches@sourceware.org>
>
> --- 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})
You consistently rewrite the Texinfo source to use @var inside the
argument lists of a @defun. I already asked why, as I don't think
this is required. I don't think you replied. So once again: why are
you doing this? what problems happen if you don't?
Otherwise, this is fine. Thanks.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Eli Zaretskii <eliz@gnu.org> writes:
>> Cc: Andrew Burgess <aburgess@redhat.com>
>> Date: Tue, 4 Apr 2023 09:21:03 +0100
>> From: Andrew Burgess via Gdb-patches <gdb-patches@sourceware.org>
>>
>> --- 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})
>
> You consistently rewrite the Texinfo source to use @var inside the
> argument lists of a @defun. I already asked why, as I don't think
> this is required. I don't think you replied. So once again: why are
> you doing this? what problems happen if you don't?
This is an unfortunate consequence of me posting many patches in similar
areas of GDB. All of these landed on the list prior to you enlightening
me that @var is not needed -- it's not me ignoring you.
I should have been more proactive in reviewing my in-flight patches for
this error to avoid wasting your time.
This change will, of course, be removed from this patch.
Thanks for your patience,
Andrew
>
> Otherwise, this is fine. Thanks.
>
> Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Andrew Burgess <aburgess@redhat.com> writes:
> Eli Zaretskii <eliz@gnu.org> writes:
>
>>> Cc: Andrew Burgess <aburgess@redhat.com>
>>> Date: Tue, 4 Apr 2023 09:21:03 +0100
>>> From: Andrew Burgess via Gdb-patches <gdb-patches@sourceware.org>
>>>
>>> --- 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})
>>
>> You consistently rewrite the Texinfo source to use @var inside the
>> argument lists of a @defun. I already asked why, as I don't think
>> this is required. I don't think you replied. So once again: why are
>> you doing this? what problems happen if you don't?
>
> This is an unfortunate consequence of me posting many patches in similar
> areas of GDB. All of these landed on the list prior to you enlightening
> me that @var is not needed -- it's not me ignoring you.
>
> I should have been more proactive in reviewing my in-flight patches for
> this error to avoid wasting your time.
>
> This change will, of course, be removed from this patch.
>
> Thanks for your patience,
> Andrew
>
>>
>> Otherwise, this is fine. Thanks.
>>
>> Reviewed-By: Eli Zaretskii <eliz@gnu.org>
I've now pushed this patch.
Thanks,
Andrew
@@ -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}.