On Tue, Oct 25, 2011 at 2:48 PM, Kevin Pouget wrote: > On Tue, Oct 25, 2011 at 2:22 PM, Eli Zaretskii wrote: >>> From: Kevin Pouget >>> 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 ? Hello, there was a line longer than 80char in unwind_reason.def, I've split it I've also added the definition for FRAME_UNWIND_FIRST_ERROR that you suggested Eli (I've truncated the example to > 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: %s" % reason_str because the full line was too long for the PDF. is it your last word for not mentioning the current value of the alias? Thanks, Kevin 2011-10-14 Kevin Pouget * frame.c (frame_stop_reason_string): Rewrite using unwind_stop_reasons.def. * frame.h (enum unwind_stop_reason): Likewise. * python/py-frame.c (gdbpy_initialize_frames): Likewise. (gdbpy_frame_stop_reason_string): Use new enum unwind_stop_reason constants for bound-checking. * unwind_stop_reasons.def: New file.