Re: [RFC][Python] gdbpy_frame_stop_reason_string bug

[Kevin Pouget <kevin.pouget@gmail.com>]

On Tue, Oct 25, 2011 at 2:22 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Kevin Pouget <kevin.pouget@gmail.com>
>> Date: Tue, 25 Oct 2011 09:20:19 +0200
>> Cc: pedro@codesourcery.com, pmuldoon@redhat.com, gdb-patches@sourceware.org,
>>       tromey@redhat.com
>>
>> >> +@item gdb.FRAME_UNWIND_FIRST_ERROR
>> >> +All the conditions after this alias are considered errors;
>> >
>> > Hmm...  This table is preceded by this text:
>> >
>> >  @defun Frame.unwind_stop_reason ()
>> >  Return an integer representing the reason why it's not possible to find
>> >  more frames toward the outermost frame.  Use
>> >  @code{gdb.frame_stop_reason_string} to convert the value returned by this
>> >  function to a string. The value can be one of:
>> >
>> > So "conditions after this alias" seems inappropriate in the list that
>> > follows, because we are not describing conditions or aliases.  Can you
>> > rephrase this to be consistent with the rest of the list.
>>
>> I'm not sure about you see wrong with "alias". We could replace it
>> with "reference" (like the & operator in C++, but also used in Python
>> and Java), but it sounds more or less the same to me.
>>
>> What do you think about:
>> "Stop reasons greater or equal to this value/alias/reference"
>
> Now that I understand the intent, I would suggest
>
>  Any stop reason greater or equal to this value indicates some kind
>  of error.  This special value facilitates writing code that tests
>  for errors in unwinding in a way that will work correctly even if
>  the list of the other values is modified in future @value{GDBN}
>  versions.  Using it, you could write:

yes, if you feel like it has to be explicited, it's better this way

@smallexample
reason = gdb.selected_frame().unwind_stop_reason ()
reason_str =  gdb.frame_stop_reason_string (reason)
if reason >=  gdb.FRAME_UNWIND_FIRST_ERROR:
    print "An error occured during the unwinding process: %s" % reason_str

@end smallexample
>
>> > And why is it important that the value is an alias for another?
>>
>> it's important because it's not a distinct value as the other ones, so
>> > frame_stop_reason_string(UNWIND_FIRST_ERROR) == frame_stop_reason_string(UNWIND_UNAVAILABLE)
>> is True, which might be counter-intuitive if you don't know that
>> UNWIND_FIRST_ERROR is an alias/reference
>
> I still don't see the importance, sorry.  Moreover, having this text
> means that we will need to update the manual each time the list of
> unwind reasons is modified, **which in a way works against this very
> feature.**

You're half right with this last sentence, but this Python value is
not here to ease *our* (GDB developers) lives, but rather for Python
developers.
this value is not meant to change very often (not to say almost
never), so I think it's not a big burden to change the documentation
as well when it happens.
The very reason why I wrote it is that I think it's useful for the
reader: when you look over this list, you can easily see what is a
normal reason for unwinders to stop, and what isn't (I think that not
so many people will actually have the chance to use it, but out of
curiosity, some people will want to read and understand it).


But that put aside, you're not convinced yet and I'm running short of
arguments ... Pedro, Tom, Phil, how do you see that ?