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

[Andrew Burgess <aburgess@redhat.com>]

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