OpenE2K
/
binutils-gdb
12
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

python doc: Rework Breakpoint.__init__ doc 

I find the documentation of the gdb.Breakpoint constructor hard to read
and not very informative, especially since we have added the new
linespec parameters.  There are multiple problems (some are subjective):

- It's not clear that you should use either the spec string or the
  explicit arguments, not both.
- It's not clear what combination of parameters you can use.
- The big block of text describing the arguments is hard to read.
- Currently, it seems like the "spec" argument is mandatory, even though
  it is not (if you use explicit linespec).
- The square bracket nesting

    [arg1 [, arg2[, arg3]]]

  makes it seems like if you specify arg3, you must specify arg1 and
  arg2 (it's not the case here).

This patch tries to address these problems.

gdb/doc/ChangeLog:

	* python.texi (Manipulating breakpoints using Python): Split doc
	of Breakpoint.__init__ in two, split text in multiple
	paragraphs, don't nest parameter square brackets.
This commit is contained in:
Simon Marchi 2017-12-13 11:26:51 -05:00
parent 79e7419204
commit 0b982d685e
2 changed files with 48 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
gdb/doc/ChangeLog
View File

@ -1,3 +1,9 @@
2017-12-13 Simon Marchi <simon.marchi@ericsson.com>
* python.texi (Manipulating breakpoints using Python): Split doc
of Breakpoint.__init__ in two, split text in multiple
paragraphs, don't nest parameter square brackets.
2017-12-12 Stafford Horne <shorne@gmail.com>
Stefan Wallentowitz <stefan@wallentowitz.de>
Franck Jullien <franck.jullien@gmail.com>

66
gdb/doc/python.texi
View File

@ -4878,30 +4878,48 @@ represented as Python @code{Long} values.
Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
class.
@defun Breakpoint.__init__ (spec @r{[}, type @r{[}, wp_class @r{[}, internal @r{[}, temporary @r{]}, source @r{]}, function @r{]}, label @r{]}, line @r{]]]]]]]]})
Create a new breakpoint according to @var{spec}, which is a string
naming the location of the breakpoint, or an expression that defines a
watchpoint. The contents can be any location recognized by the
@code{break} command or, in the case of a watchpoint, by the
@code{watch} command. Alternatively, create a new a explicit location
breakpoint (@pxref{Explicit Locations}) according to the
specifications contained in the key words @var{source},
@var{function}, @var{label} and @var{line}. The optional @var{type}
denotes the breakpoint to create from the types defined later in this
chapter. This argument can be either @code{gdb.BP_BREAKPOINT} or
@code{gdb.BP_WATCHPOINT}; it defaults to @code{gdb.BP_BREAKPOINT}.
The optional @var{internal} argument allows the breakpoint to become
invisible to the user. The breakpoint will neither be reported when
created, nor will it be listed in the output from @code{info
breakpoints} (but will be listed with the @code{maint info
breakpoints} command). The optional @var{temporary} argument makes
the breakpoint a temporary breakpoint. Temporary breakpoints are
deleted after they have been hit. Any further access to the Python
breakpoint after it has been hit will result in a runtime error (as
that breakpoint has now been automatically deleted). The optional
@var{wp_class} argument defines the class of watchpoint to create, if
@var{type} is @code{gdb.BP_WATCHPOINT}. If a watchpoint class is not
provided, it is assumed to be a @code{gdb.WP_WRITE} class.
A breakpoint can be created using one of the two forms of the
@code{gdb.Breakpoint} constructor. The first one accepts a string
like one would pass to the @code{break}
(@pxref{Set Breaks,,Setting Breakpoints}) and @code{watch}
(@pxref{Set Watchpoints, , Setting Watchpoints}) commands, and can be used to
create both breakpoints and watchpoints. The second accepts separate Python
arguments similar to @ref{Explicit Locations}, and can only be used to create
breakpoints.
@defun Breakpoint.__init__ (spec @r{[}, type @r{][}, wp_class @r{][}, internal @r{][}, temporary @r{]})
Create a new breakpoint according to @var{spec}, which is a string naming the
location of a breakpoint, or an expression that defines a watchpoint. The
string should describe a location in a format recognized by the @code{break}
command (@pxref{Set Breaks,,Setting Breakpoints}) or, in the case of a
watchpoint, by the @code{watch} command
(@pxref{Set Watchpoints, , Setting Watchpoints}).
The optional @var{type} argument specifies the type of the breakpoint to create,
as defined below.
The optional @var{wp_class} argument defines the class of watchpoint to create,
if @var{type} is @code{gdb.BP_WATCHPOINT}. If @var{wp_class} is omitted, it
defaults to @code{gdb.WP_WRITE}.
The optional @var{internal} argument allows the breakpoint to become invisible
to the user. The breakpoint will neither be reported when created, nor will it
be listed in the output from @code{info breakpoints} (but will be listed with
the @code{maint info breakpoints} command).
The optional @var{temporary} argument makes the breakpoint a temporary
breakpoint. Temporary breakpoints are deleted after they have been hit. Any
further access to the Python breakpoint after it has been hit will result in a
runtime error (as that breakpoint has now been automatically deleted).
@end defun
@defun Breakpoint.__init__ (@r{[} source @r{][}, function @r{][}, label @r{][}, line @r{]}, @r{][} internal @r{][}, temporary @r{]})
This second form of creating a new breakpoint specifies the explicit
location (@pxref{Explicit Locations}) using keywords. The new breakpoint will
be created in the specified source file @var{source}, at the specified
@var{function}, @var{label} and @var{line}.
@var{internal} and @var{temporary} have the same usage as explained previously.
@end defun
The available types are represented by constants defined in the @code{gdb}