python doc: Rework Breakpoint.__init__ doc
authorSimon Marchi <simon.marchi@ericsson.com>
Wed, 13 Dec 2017 16:26:51 +0000 (11:26 -0500)
committerSimon Marchi <simon.marchi@ericsson.com>
Wed, 13 Dec 2017 16:27:04 +0000 (11:27 -0500)
commit0b982d685e840948eed4619843a0cc5ce8991d6c
tree7040548b192039e8458f35f5cdbf4dc2d59cc615
parent79e741920446582bd0e09f3e2b9f899c258efa56
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
gdb/doc/python.texi