From 0b982d685e840948eed4619843a0cc5ce8991d6c Mon Sep 17 00:00:00 2001 From: Simon Marchi Date: Wed, 13 Dec 2017 11:26:51 -0500 Subject: [PATCH] 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. --- gdb/doc/ChangeLog | 6 +++++ gdb/doc/python.texi | 66 ++++++++++++++++++++++++++++----------------- 2 files changed, 48 insertions(+), 24 deletions(-) diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 4e032ec605..6a22443fad 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,9 @@ +2017-12-13 Simon Marchi + + * 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 Stefan Wallentowitz Franck Jullien diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index 28a7a1a9f5..22b49b3525 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -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} -- 2.34.1