From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTPS id F19F33858D33 for ; Thu, 27 Apr 2023 13:04:58 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org F19F33858D33 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=redhat.com DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1682600698; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=ay1qQj7gIZENbw8um5Lb0hoAjX8Mlf/C4bwHoerpD24=; b=VeDIvyV7bv+GnSoF33UStEvl92GVMJJRo1yUIAkMMLgeN62XKvQzYPYh/ZdQdBZLI0A6zD HmbD6kcSFYaO2vNyWbqBCmmZ+uZkO6T9VP0dwBFvLSVPWsPMx5xeo/NlhdM6vNvtwf1Fl4 K1ahHtZsuC3R87G3LrMYakckSaNIxGs= Received: from mail-wm1-f72.google.com (mail-wm1-f72.google.com [209.85.128.72]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-481-l0YjOAC6MJGWDVCJWqCToA-1; Thu, 27 Apr 2023 09:04:48 -0400 X-MC-Unique: l0YjOAC6MJGWDVCJWqCToA-1 Received: by mail-wm1-f72.google.com with SMTP id 5b1f17b1804b1-3f16ef3bf06so29504805e9.3 for ; Thu, 27 Apr 2023 06:04:46 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1682600685; x=1685192685; h=mime-version:message-id:date:references:in-reply-to:subject:cc:to :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=ay1qQj7gIZENbw8um5Lb0hoAjX8Mlf/C4bwHoerpD24=; b=GarG5lCxo2ftX6VkKxxP1nPpnWmZHfPfh57819kje4+DD+PNPRO500XEGdZj+btWxS Vu7YPKTMl1Uajtcfu311JrJUDLZK7CuR5wME+6L4VQ1ehZ7xJsBEsBtFqpi/JtCOOuNf ho3kApSalOZZzwkOu466pkYK0buN1c9fB6ed7SZDMZjb6jsaMopE/R8b73cqs37MeLnJ ntJ9Ax2MTT2mbzcw+lYyc7PYVj/SEzn3dHqr2FFkPDqVEuLzxFrVK9RJvecS4ITSyU8S MK1gNWUMfWAjpgYdaGEokMYntuQAxYrehi0kl9+AOm1EaBS3uMedKvUKcPjMgyJwO/or 9ldg== X-Gm-Message-State: AC+VfDxaWiPN75VdxN5KL8AxkBQf3vTpJPWOdOKxj3ScGWFAw68inYEg Rf5ICf/Wf0lPNRxILMbwbV0MWz1rEfcWfXbfO4hMS5hC72WU9l/zuoAuUZYCrIg7EowcufLw298 0zYKzNq5XEJCTzsjARfmrgLKNogAgISC/O1WMhc3bm3NmxZN9rMEOpoNfSVssLm5fv+LsY/5cSs 3v3L9rSQ== X-Received: by 2002:a05:600c:ac8:b0:3f1:819d:d050 with SMTP id c8-20020a05600c0ac800b003f1819dd050mr1273144wmr.37.1682600685060; Thu, 27 Apr 2023 06:04:45 -0700 (PDT) X-Google-Smtp-Source: ACHHUZ46MYISnJZFOJpfNx2wV9SMKT1BGa329KTUyFo6yVbXrvoidSiFDAW4iYUHTl3lJ6l2wBagyw== X-Received: by 2002:a05:600c:ac8:b0:3f1:819d:d050 with SMTP id c8-20020a05600c0ac800b003f1819dd050mr1273103wmr.37.1682600684199; Thu, 27 Apr 2023 06:04:44 -0700 (PDT) Received: from localhost (11.72.115.87.dyn.plus.net. [87.115.72.11]) by smtp.gmail.com with ESMTPSA id l9-20020a05600c1d0900b003f17eded97bsm25050409wms.19.2023.04.27.06.04.43 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 27 Apr 2023 06:04:43 -0700 (PDT) From: Andrew Burgess To: gdb-patches@sourceware.org Cc: Eli Zaretskii Subject: Re: [PATCH] gdb/doc: don't use @var on @defun lines In-Reply-To: <27f86d992bf0dbd795bbffd169c9da17c1da56b0.1680791507.git.aburgess@redhat.com> References: <27f86d992bf0dbd795bbffd169c9da17c1da56b0.1680791507.git.aburgess@redhat.com> Date: Thu, 27 Apr 2023 14:04:42 +0100 Message-ID: <87cz3pbhn9.fsf@redhat.com> MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain X-Spam-Status: No, score=-11.6 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,GIT_PATCH_0,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H2,SPF_HELO_NONE,SPF_NONE,TXREP,T_PDS_OTHER_BAD_TLD,T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: 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 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