Re: [PATCH 05/10] gdb/python: add some additional methods to gdb.PendingFrame

[Eli Zaretskii <eliz@gnu.org>]

> From: Andrew Burgess <aburgess@redhat.com>
> Cc: gdb-patches@sourceware.org
> Date: Thu, 16 Mar 2023 14:28:46 +0000
> 
> Eli Zaretskii <eliz@gnu.org> 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.