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.

2 files changed, 48 insertions, 24 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 4e032ec6054..6a22443fad9 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -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>
diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 28a7a1a9f5b..22b49b35256 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}