From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from simark.ca by simark.ca with LMTP id aMj6HxLeK2SH2CIAWB0awg (envelope-from ) for ; Tue, 04 Apr 2023 04:21:38 -0400 Received: by simark.ca (Postfix, from userid 112) id 8066A1E15D; Tue, 4 Apr 2023 04:21:38 -0400 (EDT) Authentication-Results: simark.ca; dkim=pass (1024-bit key; secure) header.d=sourceware.org header.i=@sourceware.org header.a=rsa-sha256 header.s=default header.b=YVZXvP6w; dkim-atps=neutral X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on simark.ca X-Spam-Level: X-Spam-Status: No, score=-8.0 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,MAILING_LIST_MULTI,RCVD_IN_DNSWL_HI, URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.6 Received: from sourceware.org (server2.sourceware.org [8.43.85.97]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by simark.ca (Postfix) with ESMTPS id 2EFF41E0D3 for ; Tue, 4 Apr 2023 04:21:38 -0400 (EDT) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id C5B04385841E for ; Tue, 4 Apr 2023 08:21:37 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org C5B04385841E DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1680596497; bh=+0xVknna/bKOA/HaVnS9pdDi8mRDSiqV7Tu+kHKuxS8=; h=To:Cc:Subject:Date:In-Reply-To:References:List-Id: List-Unsubscribe:List-Archive:List-Post:List-Help:List-Subscribe: From:Reply-To:From; b=YVZXvP6wOdiTvI9+Y/+JL/AYgQjrMBdtsTyWrayzDHcHLtaBGCRLb+yawSrCHj7rE KlXbvZzs7WWKyAkKKVtXpF3wqYuiGPH2JIGGxhH9PZkHhbQtBc+wogq2tx+uuvFol9 WUY+j5RExfaVm5n4ne8qcCtSFiBIYvWKDi9htVuE= 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 A29763858C52 for ; Tue, 4 Apr 2023 08:21:14 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org A29763858C52 Received: from mail-qt1-f199.google.com (mail-qt1-f199.google.com [209.85.160.199]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-627-PJ7RnpgfMVGbCPgfKlcDRw-1; Tue, 04 Apr 2023 04:21:13 -0400 X-MC-Unique: PJ7RnpgfMVGbCPgfKlcDRw-1 Received: by mail-qt1-f199.google.com with SMTP id y10-20020a05622a164a00b003e38e0a3cc3so21492969qtj.14 for ; Tue, 04 Apr 2023 01:21:13 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; t=1680596473; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=+0xVknna/bKOA/HaVnS9pdDi8mRDSiqV7Tu+kHKuxS8=; b=CrI1+xOjQxf56+KmY6Vu+eMCtp5ni/92QS/4XzQppRPQt8xeHzeXFBHosJlHv3kIXo XXyJXOercK4A4vFYXVH+/2JIPvY3E2HGS9G3Bz1FENkW+Lhr+XRCV7iAzLw26uHIO5aH iYKDTrpRaHo+s7ombl0eJwTGpeysKpw/e6Hbj4FAyL3g8X6LeIQ/UgLgItUimDQyHl7A N5qUcHuM1a7inTs68lcqDldds1Hve8qNBwjI5TpMtY7dYNstIXHOeCJoLYaXIC7CT4UB 908H+ga4rGlPesxOBhtBDvUGaCBw+B3aJc2yMDfAe6BVKGT1rJMZ4kAO3HYxm23NpufS uAGg== X-Gm-Message-State: AAQBX9d6dBSw/36/MMPUtX9aINViO2zFTXC/HXbmlZKR/BbR7HcOv1fE vtx6ZFjg3HMDit+xXxcbjbtk4jHFgeiFX6by/yHhOd2afwFUbgOnwDbc8Nx1oSkZPg/3BMY2M24 bRFsXh5fVwPxwXc1IAFS3Tk1aHFgf0mQKwSkk57MP3rdtC8FtpNjcvdjRulnDK3L1UP3VzAKvre vxYc3NtQ== X-Received: by 2002:a05:622a:1aa6:b0:3e3:969e:c44a with SMTP id s38-20020a05622a1aa600b003e3969ec44amr2256748qtc.8.1680596472830; Tue, 04 Apr 2023 01:21:12 -0700 (PDT) X-Google-Smtp-Source: AKy350aMergp0tScvdXhZnwd+ZIt/jkNBbZ+yp0wJ666frWjq0KdFzrmC+HmdFg7pvO3trici/AoNA== X-Received: by 2002:a05:622a:1aa6:b0:3e3:969e:c44a with SMTP id s38-20020a05622a1aa600b003e3969ec44amr2256736qtc.8.1680596472513; Tue, 04 Apr 2023 01:21:12 -0700 (PDT) Received: from localhost (95.72.115.87.dyn.plus.net. [87.115.72.95]) by smtp.gmail.com with ESMTPSA id c30-20020ac86e9e000000b003e388264753sm3051776qtv.65.2023.04.04.01.21.12 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 04 Apr 2023 01:21:12 -0700 (PDT) To: gdb-patches@sourceware.org Cc: Andrew Burgess Subject: [PATCH 1/5] gdb/doc: improve Python Disassembler API documentation Date: Tue, 4 Apr 2023 09:21:03 +0100 Message-Id: <3cdddabce2d5acfbdb9a8c5bdcb1a205a2bd01e5.1680596378.git.aburgess@redhat.com> X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: 8bit Content-Type: text/plain; charset="US-ASCII"; x-default=true 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: , From: Andrew Burgess via Gdb-patches Reply-To: Andrew Burgess Errors-To: gdb-patches-bounces+public-inbox=simark.ca@sourceware.org Sender: "Gdb-patches" 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(-) diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index c74d586ef39..a350260559f 100644 --- 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}) 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}. -- 2.25.4