Re: [PATCH] python doc: Rework Breakpoint.__init__ doc

[Eli Zaretskii <eliz@gnu.org>]

> Date: Fri, 08 Dec 2017 12:59:31 -0500
> From: Simon Marchi <simon.marchi@polymtl.ca>
> Cc: Simon Marchi <simon.marchi@ericsson.com>, gdb-patches@sourceware.org
> 
> We have a cross-reference for break and watch just above, is it 
> necessary to put them at every reference of those commands?

No, not if they are close enough to one another.

> Alternatively, instead of adding a "(see Setting Breakpoints)", for 
> example, is it possible to make the "break" word a link itself to the 
> documentation of break?

This doesn't work well in some formats supported by Texinfo, so IMO
it's best to avoid that.

> It would work great for 
> HTML, PDF and info (formats with links), but not so much for plain text 
> formats.

Actually, it works well for HTML, less well for Info, and not at all
for PDF (because there are no hyperlinks in the printed version, only
"See this and that").

> >> +The optional @var{type} argument 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}.
> > 
> > TYPE does not denote the breakpoint, it specifies its type.  So
> > suggest to reword"
> > 
> >   The optional @var{type} argument specifies the type of the
> >   breakpoint to create, as defined below.
> 
> Done.  I understand that we get rid of the second sentence (This 
> argument can be either...)?

Not necessarily, you can keep it if you think it's useful.

> > Btw, didn't you want to describe which combinations of these keywords
> > are valid?  Or maybe you should add a cross-reference to where that is
> > described for the CLI commands.
> 
> The important part is the fact that you can't use "spec" at the same 
> time as source/line/label/function.  This should now be clear, because 
> they are defined in the two separate forms of gdb.Breakpoint().

Hmmm... now I'm confused: "at the same time" and "separate forms"
sounds like a contradiction to me.  My understanding was that one
needs to choose which constructor to use: the first or the second, and
then produce the spec accordingly.  Isn't that so?

Thanks.