This is the mail archive of the gdb-patches@sourceware.org mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [Patch v11] Debug methods in GDB Python


> Date: Mon, 3 Mar 2014 05:49:29 -0800
> From: Siva Chandra <sivachandra@google.com>
> 
> Attached is the v11 of the patch which adds the debug methods feature
> to the Python API.

Thanks.

I don't think I've reviewed the documentation part of this, so I will
do that now.

> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -87,6 +87,7 @@ qXfer:btrace:read's annex
>    ** Valid Python operations on gdb.Value objects representing
>       structs/classes invoke the corresponding overloaded operators if
>       available.
> +  ** New `Debug Methods' feature to the Python API.

OK, but perhaps one or two more sentences about this will be better.
"Debug Methods" is too general and vague to even hint on what it is
about.

> +@node Debug Methods In Python
> +@subsubsection Debug Methods In Python
> +@cindex debug method
> +@kindex debug method

I'd suggest only one index entry, not 2, and have it say "debug
methods in Python".

> +Debug methods are additional methods or replacements for existing
   ^^^^^^^^^^^^^
You are defining a term, so put it in @dfn.

> +methods of a C@t{++} class.  This feature is useful for those cases
> +where a method defined in C@t{++} source code could be inlined or
> +optimized out by the compiler, making it unavailable to @value{GDBN}.

Is this indeed only relevant to C++, or is C++ just an example?  What
about Ada, for example?

> +The debug methods feature in Python is available via the concepts of a
> +@emph{debug method matcher} and a @emph{debug method worker}.  To

Don't use @emph to emphasize new terminology; use @dfn.

> +matcher to match the class type and method name.  On a match, the
> +@code{match} method returns a list of matching @emph{worker} objects.
                                                  ^^^^^^^^^^^^^
Why @emph and not @code?

> +is also selected from among the the methods @value{GDBN} finds in the
                               ^^^^^^^
A typo.

> +C@t{++} source code.  Next, the winning debug method worker and the
> +winning C@t{++} method are compared to select an overall winner.  In
> +case of a tie between a debug method worker and a C@t{++} method, the
> +debug method worker is selected as the winner.  That is, if a winning
> +debug method worker is found to be equivalent to the winning C@t{++}
> +method, then the debug method worker is treated as a replacement for
> +the C@t{++} method.

Is there anything the reader needs to know to understand how to make a
Python method worker equivalent to the C++ method?  If so, I think we
should have that in the manual.

> +The @value{GDBN} Python API provides classes, interfaces and functions
> +to implement, register and manipulate debug methods.  The core concepts
> +involved in implementing debug methods are @emph{debug method matchers}
> +and @emph{debug method workers}.

The last sentence is a repetition of what the previous section said.
Do we really need this here?

> +An instance of @code{DebugMethodMatcher} has the following attributes:
> +
> +@defvar DebugMethodMatcher.name
> +The name of the matcher.
> +@end defvar

I think we use only the attribute name, without the class name.

> +@defun DebugMethodWroker.invoke(self, obj, args)
> +This is the method which does the @emph{work} of the debug method.
> +@code{obj} is the object on which the method is being invoked, and
> +@code{args} is the tuple of arguments to the method.  @code{obj} and the
> +elements of @code{args} are @code{gdb.Value} objects.

References to arguments of a method should be in @var, not @code.

> +@defun register_debug_method_matcher(locus, matcher, replace=False)
> +The @code{matcher} is registered with @code{locus}, replacing an
> +existing matcher with the same name as @code{matcher} if
> +@code{replace} is @code{True}.  @code{locus} can be a
> +@code{gdb.Objfile} object (@pxref{Objfiles In Python}), or a
> +@code{gdb.Progspace} object (@pxref{Program Spaces In Python}), or
> +@code{None}.  If it is @code{None}, then @code{matcher} is registered
> +globally.

Likewise.

> +@node Writing a Debug Method
> +@subsubsection Writing a Debug Method
> +@cindex writing a debug method

"writing debug methods in Python" is a better index entry, I think.

> +If an object @code{obj} of type @code{MyClass} is initialized in C@t{++}
> +code as follows:
> +
> +@smallexample
> +MyClass obj(5);
> +@end smallexample
> +
> +@noindent
> +Then, after loading the Python script defining the debug method matchers
   ^^^^
This "then" should not be capitalized.

> +and workers into @code{GDBN}, invoking @code{geta} and @code{sum}
> +methods on @code{obj} will invoke the debug methods defined above:
> +@noindent

That @noindent is not needed here.

OK with those changes.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]