Re: [PATCH] Add bp_location to Python interface

[Eli Zaretskii <eliz@gnu.org>]

> From: Kevin Pouget <kevin.pouget@gmail.com>
> Date: Mon, 9 Jan 2012 12:46:30 +0100
> Cc: pmuldoon@redhat.com
> 
> ping

Sorry for missing it the first time.

> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -9,6 +9,12 @@
>  * The binary "gdbtui" can no longer be built or installed.
>    Use "gdb -tui" instead.
>  
> +* Python scripting
> +
> +  ** A new method "gdb.Breakpoint.locations" has been added, as well as
> +     the class gdb.BpLocation to provide further details about breakpoint
> +     locations.
> +

This is OK.

> +@defun gdb.locations ()
> +Return a tuple containing a sequence of @code{gdb.BpLocation} objects 
> +(see below) associated with this breakpoint.  A breakpoint with no location
> +is a pending breakpoint (@xref{Set Breaks, , pending breakpoints}).

@pxref, not @xref, as this cross-reference is inside parentheses.

> +A breakpoint location is represented with a @code{gdb.BpLocation} object,
                                        ^^^^
"by"

> +which offers the following attributes (all read only) and methods.
> +Please note that breakpoint locations are very transient entities in
> +@value{GDBN}, so one should avoid keeping references to them.

I'd use "volatile" instead of "transient".  Also, perhaps a sentence
or two about _why_ the locations are volatile would help.  E.g., if I
knew what actions invalidate locations, I could avoid them and leave
the locations valid for longer.

> +owns this location.  This attribute is not writable.  From an implementation 
> +point of view, there is a @code{1 ... n} relation between a breakpoint and

"1 ... n" here means one to many?  If so, I suggest to say that
literally.

In any case, "@code{1 ... n}" is not a good idea, because of the
whitespace and because we use @dots{} instead of literal periods.  If
"one to many" is not what you meant, I can suggest how to mark up
whatever needs to be written here.

> +This attribute holds a reference to the @code{gdb.Inferior} inferior object

I'd drop the second instance of "inferior", it looks redundant.

> +@defun BpLocation.is_valid ()
> +Returns @code{True} if the @code{gdb.BpLocation} object is valid,
> +@code{False} if not.  A @code{gdb.BpLocation} object may be invalidated by
> +GDB at any moment for internal reasons.  All other @code{gdb.BpLocation}
> +methods and attributes will throw an exception if the object is invalid.

@value{GDBN} instead of "GDB".

In any case, the last 2 sentences sound scary: I could interpret them
as meaning I cannot trust the locations at all.  If that is indeed so,
what use are they?

Thanks.