From patchwork Thu Apr 6 14:31:56 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Burgess X-Patchwork-Id: 67462 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id C1E913858439 for ; Thu, 6 Apr 2023 14:32:28 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org C1E913858439 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1680791548; bh=pr8+/qjG7hXkmF2JYzVdSYZ6zPZciVxk7WuxgQmDqmM=; h=To:Cc:Subject:Date:List-Id:List-Unsubscribe:List-Archive: List-Post:List-Help:List-Subscribe:From:Reply-To:From; b=dCYqxB9tkG35EcJ7URcZgctkcPBpNL8t+Cd0QigxfRIB37CRKwjRQ+lSiJq4u1yS0 aJfHTwFieM2jySNXEcQHWtzJT8JdL6tFzXYKdFUzbTi8j4pYZNWKjocJmV3QY6nGyN eP30KsKRRkBuRDk9lfTtkXDBq8wjR90VOEVh6fok= X-Original-To: gdb-patches@sourceware.org Delivered-To: gdb-patches@sourceware.org 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 26AF53858D32 for ; Thu, 6 Apr 2023 14:32:03 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 26AF53858D32 Received: from mail-qt1-f197.google.com (mail-qt1-f197.google.com [209.85.160.197]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-665-AQN41VgkMiik5Zs66lHS9A-1; Thu, 06 Apr 2023 10:32:01 -0400 X-MC-Unique: AQN41VgkMiik5Zs66lHS9A-1 Received: by mail-qt1-f197.google.com with SMTP id bp42-20020a05622a1baa00b003e6748b05edso3693477qtb.2 for ; Thu, 06 Apr 2023 07:32:01 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; t=1680791521; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=pr8+/qjG7hXkmF2JYzVdSYZ6zPZciVxk7WuxgQmDqmM=; b=Bb2ePOC5qBvCdXQ79Sgw9D2FXs7m4yglb1C7Y4DOkMxT+EkT4TZDgeMZxc53cHS4Xo vuVI7GY5+kFew9Pcggf0q7q/t2wwbh9D/bjMZl2ojLDGz3HrUpWkVt4vhfWs9kBlMs9Z f+jiRD7KL1F13wUzYkpp0Y+FmrBFOOdU99K6+eCZLh3vDHhGiE4xI//pxR5wHBpaScgn SUyfJytuLZL1ku1jOVufCI6a91RAhXFZ3mRc0K6Q6z7PwGiFshgi7srDx7aUMx+gZc9K aGMh3cTg8PfJWCyJGJFSREx3WYiN7yiVyh7lMDta+ZtObJV8+xiOMN54rVCZJNilRGIH 7zEw== X-Gm-Message-State: AAQBX9d7GsJ4b/G81WKGo9hI+V3xFkcucS3WY6FcDQY5QL2pZ1ycqfUR l7wMxpsq47Y/q7bDZpCPpUJpGvE2OIgrbhTCEPjh/5Q0M0eu+U5S08Z24UdzrAsYiobuod6iKWo fjTaqApRZ695QOcApxcEMpKCePLcOkMFj7eY9mZyS1L2hGI8AdvYI90ZElikO27caF3ETNr8zlb JcXTNCGw== X-Received: by 2002:ad4:5dea:0:b0:56e:b1c8:381b with SMTP id jn10-20020ad45dea000000b0056eb1c8381bmr4513744qvb.31.1680791520916; Thu, 06 Apr 2023 07:32:00 -0700 (PDT) X-Google-Smtp-Source: AKy350ZsGDEwIsUkG8fjL6GEJ7/pYg67vkGCBY0QfCjOupZ8HhuZoZZkSvg5A1AzmPu1eKJo8oxe8A== X-Received: by 2002:ad4:5dea:0:b0:56e:b1c8:381b with SMTP id jn10-20020ad45dea000000b0056eb1c8381bmr4513707qvb.31.1680791520428; Thu, 06 Apr 2023 07:32:00 -0700 (PDT) Received: from localhost (95.72.115.87.dyn.plus.net. [87.115.72.95]) by smtp.gmail.com with ESMTPSA id kl5-20020a056214518500b005dd8b934595sm556533qvb.45.2023.04.06.07.31.59 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Apr 2023 07:32:00 -0700 (PDT) To: gdb-patches@sourceware.org Cc: Andrew Burgess Subject: [PATCH] gdb/doc: don't use @var on @defun lines Date: Thu, 6 Apr 2023 15:31:56 +0100 Message-Id: <27f86d992bf0dbd795bbffd169c9da17c1da56b0.1680791507.git.aburgess@redhat.com> X-Mailer: git-send-email 2.25.4 MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-11.7 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 autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Andrew Burgess via Gdb-patches From: Andrew Burgess Reply-To: Andrew Burgess Errors-To: gdb-patches-bounces+patchwork=sourceware.org@sourceware.org Sender: "Gdb-patches" 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(-) base-commit: d344cef4bf500f01ae326c2bd844a736de50fa41 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