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