[Bug python/19808] New: python unwinder documentation could use some love

["tromey at sourceware dot org" <sourceware-bugzilla at sourceware dot org>]

https://sourceware.org/bugzilla/show_bug.cgi?id=19808

            Bug ID: 19808
           Summary: python unwinder documentation could use some love
           Product: gdb
           Version: unknown
            Status: NEW
          Severity: normal
          Priority: P2
         Component: python
          Assignee: unassigned at sourceware dot org
          Reporter: tromey at sourceware dot org
  Target Milestone: ---

The python unwinder documentation is a bit unclear, IMO, and could use
some updates.

The documentation for create_unwind_info says:

     'sp, pc, special'
          'frame_id_build_special (FRAME_ID.sp, FRAME_ID.pc,
          FRAME_ID.special)'

     'sp, pc'
          'frame_id_build (FRAME_ID.sp, FRAME_ID.pc)'

          This is the most common case.

     'sp'
          'frame_id_build_wild (FRAME_ID.sp)'


This doesn't really mean anything unless you already know quite a bit
about the gdb frame internals.  I think that rather than refer to internal
functions, this text should explain the meaning of these different calls.
(Especially since I think two of these are generally uninteresting.)


Nothing in the docs explains the meaning of the parameters to the frame id.
It should at least mention that these are intended to be the "unchanging"
versions, say the CFA and the start PC of the function.

(Also, gdb should just export a generic frame id object so that all users
don't have to invent their own.  This could be put in unwinder.py.)

-- 
You are receiving this mail because:
You are on the CC list for the bug.