[PATCH] gdb/doc: don't use @var on @defun lines

[PATCH] gdb/doc: don't use @var on @defun lines

[Andrew Burgess]

In a recent patch tried to add a use of @var to a @defun line.  During
review it was pointed out that this was bad style, and indeed, in
python.texi, most @defun lines don't use @var:

  @defun lines with no arguments: 91
  @defun lines with arguments and no @var: 95
  @defun lines with arguments and @var: 20

In this commit I propose to remove all uses of @var from @defun lines,
this makes the docs a little more consistent.
---
 gdb/doc/python.texi | 40 ++++++++++++++++++++--------------------
 1 file changed, 20 insertions(+), 20 deletions(-)

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 1315ddcacbc..32455c58924 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -621,7 +621,7 @@
 connection objects are in no particular order in the returned list.
 @end defun
 
-@defun gdb.format_address (@var{address} @r{[}, @var{progspace}, @var{architecture}@r{]})
+@defun gdb.format_address (address @r{[}, progspace, architecture@r{]})
 Return a string in the format @samp{@var{addr}
 <@var{symbol}+@var{offset}>}, where @var{addr} is @var{address}
 formatted in hexadecimal, @var{symbol} is the symbol whose address is
@@ -894,7 +894,7 @@
 
 The following methods are provided:
 
-@defun Value.__init__ (@var{val})
+@defun Value.__init__ (val)
 Many Python values can be converted directly to a @code{gdb.Value} via
 this object initializer.  Specifically:
 
@@ -931,7 +931,7 @@
 @end table
 @end defun
 
-@defun Value.__init__ (@var{val}, @var{type})
+@defun Value.__init__ (val, type)
 This second form of the @code{gdb.Value} constructor returns a
 @code{gdb.Value} of type @var{type} where the value contents are taken
 from the Python buffer object specified by @var{val}.  The number of
@@ -1439,7 +1439,7 @@
 @end table
 @end defun
 
-@defun Type.array (@var{n1} @r{[}, @var{n2}@r{]})
+@defun Type.array (n1 @r{[}, n2@r{]})
 Return a new @code{gdb.Type} object which represents an array of this
 type.  If one argument is given, it is the inclusive upper bound of
 the array; in this case the lower bound is zero.  If two arguments are
@@ -1448,7 +1448,7 @@
 must not be negative, but the bounds can be.
 @end defun
 
-@defun Type.vector (@var{n1} @r{[}, @var{n2}@r{]})
+@defun Type.vector (n1 @r{[}, n2@r{]})
 Return a new @code{gdb.Type} object which represents a vector of this
 type.  If one argument is given, it is the inclusive upper bound of
 the vector; in this case the lower bound is zero.  If two arguments are
@@ -2899,7 +2899,7 @@
 from this class, so long as any user created unwinder has the required
 @code{name} and @code{enabled} attributes.
 
-@defun gdb.unwinder.Unwinder.__init__(@var{name})
+@defun gdb.unwinder.Unwinder.__init__(name)
 The @var{name} is a string used to reference this unwinder within some
 @value{GDBN} commands (@pxref{Managing Registered Unwinders}).
 @end defun
@@ -2925,7 +2925,7 @@
 
 @code{gdb.unwinder.FrameId} has the following method:
 
-@defun gdb.unwinder.FrameId.__init__(@var{sp}, @var{pc}, @var{special} = @code{None})
+@defun gdb.unwinder.FrameId.__init__(sp, pc, special = @code{None})
 The @var{sp} and @var{pc} arguments are required and should be either
 a @code{gdb.Value} object, or an integer.
 
@@ -4160,7 +4160,7 @@
 command is implemented using an instance of the @code{gdb.Command}
 class, most commonly using a subclass.
 
-@defun Command.__init__ (name, @var{command_class} @r{[}, @var{completer_class} @r{[}, @var{prefix}@r{]]})
+@defun Command.__init__ (name, command_class @r{[}, completer_class @r{[}, prefix@r{]]})
 The object initializer for @code{Command} registers the new command
 with @value{GDBN}.  This initializer is normally invoked from the
 subclass' own @code{__init__} method.
@@ -4604,7 +4604,7 @@
 behavior in @value{GDBN}.  Similarly, you can define parameters that
 can be used to influence behavior in custom Python scripts and commands.
 
-@defun Parameter.__init__ (name, @var{command-class}, @var{parameter-class} @r{[}, @var{enum-sequence}@r{]})
+@defun Parameter.__init__ (name, command-class, parameter-class @r{[}, enum-sequence@r{]})
 The object initializer for @code{Parameter} registers the new
 parameter with @value{GDBN}.  This initializer is normally invoked
 from the subclass' own @code{__init__} method.
@@ -4838,7 +4838,7 @@
 string for the new class.
 @end defun
 
-@defun Function.invoke (@var{*args})
+@defun Function.invoke (*args)
 When a convenience function is evaluated, its arguments are converted
 to instances of @code{gdb.Value}, and then the function's
 @code{invoke} method is called.  Note that @value{GDBN} does not
@@ -6489,7 +6489,7 @@
 Return the name (string value) of the architecture.
 @end defun
 
-@defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]})
+@defun Architecture.disassemble (start_pc @r{[}, end_pc @r{[}, count@r{]]})
 Return a list of disassembled instructions starting from the memory
 address @var{start_pc}.  The optional arguments @var{end_pc} and
 @var{count} determine the number of instructions in the returned list.
@@ -6541,7 +6541,7 @@
 @end defun
 
 @anchor{gdbpy_architecture_registers}
-@defun Architecture.registers (@r{[} @var{reggroup} @r{]})
+@defun Architecture.registers (@r{[} reggroup @r{]})
 Return a @code{gdb.RegisterDescriptorIterator} (@pxref{Registers In
 Python}) for all of the registers in @var{reggroup}, a string that is
 the name of a register group.  If @var{reggroup} is omitted, or is the
@@ -6581,7 +6581,7 @@
 It is also possible to lookup a register descriptor based on its name
 using the following @code{gdb.RegisterDescriptorIterator} function:
 
-@defun RegisterDescriptorIterator.find (@var{name})
+@defun RegisterDescriptorIterator.find (name)
 Takes @var{name} as an argument, which must be a string, and returns a
 @code{gdb.RegisterDescriptor} for the register with that name, or
 @code{None} if there is no register with that name.
@@ -6704,7 +6704,7 @@
 a @code{gdb.RemoteTargetConnection} has the following method:
 
 @kindex maint packet
-@defun RemoteTargetConnection.send_packet (@var{packet})
+@defun RemoteTargetConnection.send_packet (packet)
 This method sends @var{packet} to the remote target and returns the
 response.  The @var{packet} should either be a @code{bytes} object, or
 a @code{Unicode} string.
@@ -6747,7 +6747,7 @@
 New TUI (@pxref{TUI}) windows can be implemented in Python.
 
 @findex gdb.register_window_type
-@defun gdb.register_window_type (@var{name}, @var{factory})
+@defun gdb.register_window_type (name, factory)
 Because TUI windows are created and destroyed depending on the layout
 the user chooses, new window types are implemented by registering a
 factory function with @value{GDBN}.
@@ -6798,7 +6798,7 @@
 Remove all the contents of the window.
 @end defun
 
-@defun TuiWindow.write (@var{string} @r{[}, @var{full_window}@r{]})
+@defun TuiWindow.write (string @r{[}, full_window@r{]})
 Write @var{string} to the window.  @var{string} can contain ANSI
 terminal escape styling sequences; @value{GDBN} will translate these
 as appropriate for the terminal.
@@ -6839,7 +6839,7 @@
 send output to the @code{gdb.TuiWindow}.
 @end defun
 
-@defun Window.hscroll (@var{num})
+@defun Window.hscroll (num)
 This is a request to scroll the window horizontally.  @var{num} is the
 amount by which to scroll, with negative numbers meaning to scroll
 right.  In the TUI model, it is the viewport that moves, not the
@@ -6847,7 +6847,7 @@
 right, and so the content should appear to move to the left.
 @end defun
 
-@defun Window.vscroll (@var{num})
+@defun Window.vscroll (num)
 This is a request to scroll the window vertically.  @var{num} is the
 amount by which to scroll, with negative numbers meaning to scroll
 backward.  In the TUI model, it is the viewport that moves, not the
@@ -6855,7 +6855,7 @@
 and so the content should appear to move up.
 @end defun
 
-@defun Window.click (@var{x}, @var{y}, @var{button})
+@defun Window.click (x, y, button)
 This is called on a mouse click in this window.  @var{x} and @var{y} are
 the mouse coordinates inside the window (0-based, from the top left
 corner), and @var{button} specifies which mouse button was used, whose
@@ -7028,7 +7028,7 @@
 @w{@code{Disassembler.__call__}}, and represents a single disassembled
 instruction.  This class has the following properties and methods:
 
-@defun DisassemblerResult.__init__ (@var{length}, @var{string})
+@defun DisassemblerResult.__init__ (length, string)
 Initialize an instance of this class, @var{length} is the length of
 the disassembled instruction in bytes, which must be greater than
 zero, and @var{string} is a non-empty string that represents the

base-commit: d344cef4bf500f01ae326c2bd844a736de50fa41
-- 
2.25.4

Re: [PATCH] gdb/doc: don't use @var on @defun lines

[Andrew Burgess]

Eli,

Given your feedback on other patches that @var on a @defun line is not
desirable I assume I could probably push this as obvious?

Thanks,
Andrew


Andrew Burgess <aburgess@redhat.com> writes:

> In a recent patch tried to add a use of @var to a @defun line.  During
> review it was pointed out that this was bad style, and indeed, in
> python.texi, most @defun lines don't use @var:
>
>   @defun lines with no arguments: 91
>   @defun lines with arguments and no @var: 95
>   @defun lines with arguments and @var: 20
>
> In this commit I propose to remove all uses of @var from @defun lines,
> this makes the docs a little more consistent.
> ---
>  gdb/doc/python.texi | 40 ++++++++++++++++++++--------------------
>  1 file changed, 20 insertions(+), 20 deletions(-)
>
> diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
> index 1315ddcacbc..32455c58924 100644
> --- a/gdb/doc/python.texi
> +++ b/gdb/doc/python.texi
> @@ -621,7 +621,7 @@
>  connection objects are in no particular order in the returned list.
>  @end defun
>  
> -@defun gdb.format_address (@var{address} @r{[}, @var{progspace}, @var{architecture}@r{]})
> +@defun gdb.format_address (address @r{[}, progspace, architecture@r{]})
>  Return a string in the format @samp{@var{addr}
>  <@var{symbol}+@var{offset}>}, where @var{addr} is @var{address}
>  formatted in hexadecimal, @var{symbol} is the symbol whose address is
> @@ -894,7 +894,7 @@
>  
>  The following methods are provided:
>  
> -@defun Value.__init__ (@var{val})
> +@defun Value.__init__ (val)
>  Many Python values can be converted directly to a @code{gdb.Value} via
>  this object initializer.  Specifically:
>  
> @@ -931,7 +931,7 @@
>  @end table
>  @end defun
>  
> -@defun Value.__init__ (@var{val}, @var{type})
> +@defun Value.__init__ (val, type)
>  This second form of the @code{gdb.Value} constructor returns a
>  @code{gdb.Value} of type @var{type} where the value contents are taken
>  from the Python buffer object specified by @var{val}.  The number of
> @@ -1439,7 +1439,7 @@
>  @end table
>  @end defun
>  
> -@defun Type.array (@var{n1} @r{[}, @var{n2}@r{]})
> +@defun Type.array (n1 @r{[}, n2@r{]})
>  Return a new @code{gdb.Type} object which represents an array of this
>  type.  If one argument is given, it is the inclusive upper bound of
>  the array; in this case the lower bound is zero.  If two arguments are
> @@ -1448,7 +1448,7 @@
>  must not be negative, but the bounds can be.
>  @end defun
>  
> -@defun Type.vector (@var{n1} @r{[}, @var{n2}@r{]})
> +@defun Type.vector (n1 @r{[}, n2@r{]})
>  Return a new @code{gdb.Type} object which represents a vector of this
>  type.  If one argument is given, it is the inclusive upper bound of
>  the vector; in this case the lower bound is zero.  If two arguments are
> @@ -2899,7 +2899,7 @@
>  from this class, so long as any user created unwinder has the required
>  @code{name} and @code{enabled} attributes.
>  
> -@defun gdb.unwinder.Unwinder.__init__(@var{name})
> +@defun gdb.unwinder.Unwinder.__init__(name)
>  The @var{name} is a string used to reference this unwinder within some
>  @value{GDBN} commands (@pxref{Managing Registered Unwinders}).
>  @end defun
> @@ -2925,7 +2925,7 @@
>  
>  @code{gdb.unwinder.FrameId} has the following method:
>  
> -@defun gdb.unwinder.FrameId.__init__(@var{sp}, @var{pc}, @var{special} = @code{None})
> +@defun gdb.unwinder.FrameId.__init__(sp, pc, special = @code{None})
>  The @var{sp} and @var{pc} arguments are required and should be either
>  a @code{gdb.Value} object, or an integer.
>  
> @@ -4160,7 +4160,7 @@
>  command is implemented using an instance of the @code{gdb.Command}
>  class, most commonly using a subclass.
>  
> -@defun Command.__init__ (name, @var{command_class} @r{[}, @var{completer_class} @r{[}, @var{prefix}@r{]]})
> +@defun Command.__init__ (name, command_class @r{[}, completer_class @r{[}, prefix@r{]]})
>  The object initializer for @code{Command} registers the new command
>  with @value{GDBN}.  This initializer is normally invoked from the
>  subclass' own @code{__init__} method.
> @@ -4604,7 +4604,7 @@
>  behavior in @value{GDBN}.  Similarly, you can define parameters that
>  can be used to influence behavior in custom Python scripts and commands.
>  
> -@defun Parameter.__init__ (name, @var{command-class}, @var{parameter-class} @r{[}, @var{enum-sequence}@r{]})
> +@defun Parameter.__init__ (name, command-class, parameter-class @r{[}, enum-sequence@r{]})
>  The object initializer for @code{Parameter} registers the new
>  parameter with @value{GDBN}.  This initializer is normally invoked
>  from the subclass' own @code{__init__} method.
> @@ -4838,7 +4838,7 @@
>  string for the new class.
>  @end defun
>  
> -@defun Function.invoke (@var{*args})
> +@defun Function.invoke (*args)
>  When a convenience function is evaluated, its arguments are converted
>  to instances of @code{gdb.Value}, and then the function's
>  @code{invoke} method is called.  Note that @value{GDBN} does not
> @@ -6489,7 +6489,7 @@
>  Return the name (string value) of the architecture.
>  @end defun
>  
> -@defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]})
> +@defun Architecture.disassemble (start_pc @r{[}, end_pc @r{[}, count@r{]]})
>  Return a list of disassembled instructions starting from the memory
>  address @var{start_pc}.  The optional arguments @var{end_pc} and
>  @var{count} determine the number of instructions in the returned list.
> @@ -6541,7 +6541,7 @@
>  @end defun
>  
>  @anchor{gdbpy_architecture_registers}
> -@defun Architecture.registers (@r{[} @var{reggroup} @r{]})
> +@defun Architecture.registers (@r{[} reggroup @r{]})
>  Return a @code{gdb.RegisterDescriptorIterator} (@pxref{Registers In
>  Python}) for all of the registers in @var{reggroup}, a string that is
>  the name of a register group.  If @var{reggroup} is omitted, or is the
> @@ -6581,7 +6581,7 @@
>  It is also possible to lookup a register descriptor based on its name
>  using the following @code{gdb.RegisterDescriptorIterator} function:
>  
> -@defun RegisterDescriptorIterator.find (@var{name})
> +@defun RegisterDescriptorIterator.find (name)
>  Takes @var{name} as an argument, which must be a string, and returns a
>  @code{gdb.RegisterDescriptor} for the register with that name, or
>  @code{None} if there is no register with that name.
> @@ -6704,7 +6704,7 @@
>  a @code{gdb.RemoteTargetConnection} has the following method:
>  
>  @kindex maint packet
> -@defun RemoteTargetConnection.send_packet (@var{packet})
> +@defun RemoteTargetConnection.send_packet (packet)
>  This method sends @var{packet} to the remote target and returns the
>  response.  The @var{packet} should either be a @code{bytes} object, or
>  a @code{Unicode} string.
> @@ -6747,7 +6747,7 @@
>  New TUI (@pxref{TUI}) windows can be implemented in Python.
>  
>  @findex gdb.register_window_type
> -@defun gdb.register_window_type (@var{name}, @var{factory})
> +@defun gdb.register_window_type (name, factory)
>  Because TUI windows are created and destroyed depending on the layout
>  the user chooses, new window types are implemented by registering a
>  factory function with @value{GDBN}.
> @@ -6798,7 +6798,7 @@
>  Remove all the contents of the window.
>  @end defun
>  
> -@defun TuiWindow.write (@var{string} @r{[}, @var{full_window}@r{]})
> +@defun TuiWindow.write (string @r{[}, full_window@r{]})
>  Write @var{string} to the window.  @var{string} can contain ANSI
>  terminal escape styling sequences; @value{GDBN} will translate these
>  as appropriate for the terminal.
> @@ -6839,7 +6839,7 @@
>  send output to the @code{gdb.TuiWindow}.
>  @end defun
>  
> -@defun Window.hscroll (@var{num})
> +@defun Window.hscroll (num)
>  This is a request to scroll the window horizontally.  @var{num} is the
>  amount by which to scroll, with negative numbers meaning to scroll
>  right.  In the TUI model, it is the viewport that moves, not the
> @@ -6847,7 +6847,7 @@
>  right, and so the content should appear to move to the left.
>  @end defun
>  
> -@defun Window.vscroll (@var{num})
> +@defun Window.vscroll (num)
>  This is a request to scroll the window vertically.  @var{num} is the
>  amount by which to scroll, with negative numbers meaning to scroll
>  backward.  In the TUI model, it is the viewport that moves, not the
> @@ -6855,7 +6855,7 @@
>  and so the content should appear to move up.
>  @end defun
>  
> -@defun Window.click (@var{x}, @var{y}, @var{button})
> +@defun Window.click (x, y, button)
>  This is called on a mouse click in this window.  @var{x} and @var{y} are
>  the mouse coordinates inside the window (0-based, from the top left
>  corner), and @var{button} specifies which mouse button was used, whose
> @@ -7028,7 +7028,7 @@
>  @w{@code{Disassembler.__call__}}, and represents a single disassembled
>  instruction.  This class has the following properties and methods:
>  
> -@defun DisassemblerResult.__init__ (@var{length}, @var{string})
> +@defun DisassemblerResult.__init__ (length, string)
>  Initialize an instance of this class, @var{length} is the length of
>  the disassembled instruction in bytes, which must be greater than
>  zero, and @var{string} is a non-empty string that represents the
>
> base-commit: d344cef4bf500f01ae326c2bd844a736de50fa41
> -- 
> 2.25.4

Re: [PATCH] gdb/doc: don't use @var on @defun lines

[Eli Zaretskii]

> From: Andrew Burgess <aburgess@redhat.com>
> Cc: Eli Zaretskii <eliz@gnu.org>
> Date: Thu, 27 Apr 2023 14:04:42 +0100
> 
> Given your feedback on other patches that @var on a @defun line is not
> desirable I assume I could probably push this as obvious?

Yes, thanks.

Re: [PATCH] gdb/doc: don't use @var on @defun lines

[Tom Tromey]

>> Given your feedback on other patches that @var on a @defun line is not
>> desirable I assume I could probably push this as obvious?

Eli> Yes, thanks.

I also sent a patch like this, but my version fixed another issue:

https://sourceware.org/pipermail/gdb-patches/2023-April/198659.html

... namely that one variable name seemed strange, as it is invalid in
Python.

I can rebase that once Andrew's goes in.

Tom

Re: [PATCH] gdb/doc: don't use @var on @defun lines

[Eli Zaretskii]

> From: Tom Tromey <tromey@adacore.com>
> Cc: Andrew Burgess <aburgess@redhat.com>,  Eli Zaretskii <eliz@gnu.org>
> Date: Thu, 27 Apr 2023 10:45:27 -0600
> 
> >> Given your feedback on other patches that @var on a @defun line is not
> >> desirable I assume I could probably push this as obvious?
> 
> Eli> Yes, thanks.
> 
> I also sent a patch like this, but my version fixed another issue:
> 
> https://sourceware.org/pipermail/gdb-patches/2023-April/198659.html
> 
> ... namely that one variable name seemed strange, as it is invalid in
> Python.
> 
> I can rebase that once Andrew's goes in.

Any such changes are obvious, thanks.

Re: [PATCH] gdb/doc: don't use @var on @defun lines

[Andrew Burgess]

Tom Tromey <tromey@adacore.com> writes:

>>> Given your feedback on other patches that @var on a @defun line is not
>>> desirable I assume I could probably push this as obvious?
>
> Eli> Yes, thanks.
>
> I also sent a patch like this, but my version fixed another issue:
>
> https://sourceware.org/pipermail/gdb-patches/2023-April/198659.html
>
> ... namely that one variable name seemed strange, as it is invalid in
> Python.
>
> I can rebase that once Andrew's goes in.

Tom,

If you patch is a super-set of mine, then you should just go ahead and
push yours.

Thanks,
Andrew

Re: [PATCH] gdb/doc: don't use @var on @defun lines

[Tom Tromey]

Andrew> If you patch is a super-set of mine, then you should just go ahead and
Andrew> push yours.

Alright.  I think it is, so I'm going to rebase & push it now.

Tom