From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from eggs.gnu.org (eggs.gnu.org [IPv6:2001:470:142:3::10]) by sourceware.org (Postfix) with ESMTPS id 43DB33858D35 for ; Thu, 16 Mar 2023 14:47:07 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 43DB33858D35 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=gnu.org Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=gnu.org Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pcosk-0000j6-N7; Thu, 16 Mar 2023 10:47:06 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=vyU8mp092Gc0yr1vH2JukPcENTABb7OBtGw9U9wIOSs=; b=GCud6Sxa54fC xfErG+ok1OfHfuWY1OdJqu2xvRrt3cleGpCVa+9pP6Ihfml6yzzVhjL3pfUXIl8TLGDs5rC4PRzIa lWwAQ7nmIaDoDMI78Ze+I5g9/nd7E374aqKY49cyG9e0JG2QjOxad1bqaDXpUxV7XE2we/wxTGb8C qBnkQTU2D9gR6sC3xXmg+5Fidr9A3kLSMPNEz0vSQ6K794ifNDVN8ZvlUxzBcvga+4cvYo/nbKXLs mCevRGtZSsGq3wwsliojk8MhLeHTKt2fkyxqcZPkgmtArnnLRHkHdoz4dAJFC7zOsuUT/Ylnn7HRR YFrdEF/6XTkhbZiu8DdglQ==; Received: from [87.69.77.57] (helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pcosk-0001CP-1H; Thu, 16 Mar 2023 10:47:06 -0400 Date: Thu, 16 Mar 2023 16:46:57 +0200 Message-Id: <833564rbxa.fsf@gnu.org> From: Eli Zaretskii To: Andrew Burgess Cc: gdb-patches@sourceware.org In-Reply-To: <878rfwg481.fsf@redhat.com> (message from Andrew Burgess on Thu, 16 Mar 2023 14:28:46 +0000) Subject: Re: [PATCH 05/10] gdb/python: add some additional methods to gdb.PendingFrame References: <5bd7327ee61fd1634235cd4ffddbfbc91d392e03.1678460067.git.aburgess@redhat.com> <83y1o4y5nu.fsf@gnu.org> <87h6unfxge.fsf@redhat.com> <83lejzsd2x.fsf@gnu.org> <878rfwg481.fsf@redhat.com> X-Spam-Status: No, score=1.7 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_BARRACUDACENTRAL,SPF_HELO_PASS,SPF_PASS,TXREP autolearn=no autolearn_force=no version=3.4.6 X-Spam-Level: * X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: > From: Andrew Burgess > Cc: gdb-patches@sourceware.org > Date: Thu, 16 Mar 2023 14:28:46 +0000 > > Eli Zaretskii writes: > > >> >> + - gdb.PendingFrame.find_sal(): Return a gdb.Symtab_and_line > >> >> + object for the current location within the pending frame, or > >> >> + None. > >> >> + - gdb.PendingFrame.block(): Return a gdb.Block for the current > >> >> + pending frame, or None. > >> >> + - gdb.PendingFrame.function(): Return a gdb.Symbol for the > >> >> + current pending frame, or None. > >> > > >> > Btw, why do you follow each method name with a "()"? That looks like > >> > a call with no arguments, which is not what you mean, right? > >> > >> I did indeed mean a call with no arguments. These would be used like > >> this: > >> > >> class TestUnwinder(Unwinder): > >> def __init__(self): > >> super().__init__("Unwinder_Name") > >> > >> def __call__(self, pending_frame): > >> is_valid = pending_frame.is_valid() > >> name = pending_frame.name() > >> pc = pending_frame.pc() > >> language = pending_frame.language() > >> sal = pending_frame.find_sal() > >> block = pending_frame.block() > >> function = pending_frame.function() > > > > That's not my point. AFAIU, the text on which I commented documents > > the methods and what each one of them does. Then the "()" has no > > place there, since you are naming the methods, not showing how to call > > them. Right? > > I like to think we're documenting how to use the API, which includes how > to call them. That's true in Texinfo, but my comment was about NEWS. > @defvar ClassName.Attribute > Contains a value. > @end defvar > > @defun ClassName.NoArgsMethod() > Does stuff. > @end defun > > @defun ClassName.TakesArgs(@var{arg1}, @var{arg2}) > Does other stuff. > @end defun > > If I've understood your correctly (sorry if I have not), then you are > suggesting dropping the '()' from the 'NoArgsMethod' case. Not in Texinfo, no. In Texinfo, we do show the signature when we document a function or a method. But NEWS is mostly free-form text, and in free-form text there's no reason to append a signature whenever you mention the name of a function or a method.