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 A29763858C52 for ; Tue, 4 Apr 2023 08:21:14 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org A29763858C52 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=1680596474; 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: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=+0xVknna/bKOA/HaVnS9pdDi8mRDSiqV7Tu+kHKuxS8=; b=Ssejpkh7ELI/plBQtZBWxe2X19q5KREYcVppqZlSlL5SWlDKR690jZgLMFdyw1hTfD7iPa QoV2Tk6L1PYOqfrNrHJELcH6rbfmKZgli9+n4Ikl/FM54wlzbmZtwqZmhL/FkJoxVfYDxo aHvxxskF+ijMkdOkoabRtIk6VTXzhfk= 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) From: Andrew Burgess 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-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 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: 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