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

[Andrew Burgess <aburgess@redhat.com>]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Andrew Burgess <aburgess@redhat.com>
>> Cc: gdb-patches@sourceware.org
>> Date: Tue, 14 Mar 2023 10:18:09 +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.  I do end up being a user of the Python API docs pretty
extensively, and when I do I'm looking for how do I call this method,
and what arguments should I be passing.

As far as I can tell the most common style in the docs is to include the
argument list, and I think it would be more confusing if we only
included the argument list for the case when there were some actual
arguments.  Why leave the user to infer the empty argument list when we
can just go ahead and say it.

Finally, this becomes more confusing I think with Python that supports
both methods (requires parenthesis to call) and attributes which don't
require parenthesis to access.  Thus under the current scheme we have:

  @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.  But I think
this would be inconsistent with the 'TakesArgs' method, and risks
confusion with the 'Attribute'.

Thanks,
Andrew