From: Simon Marchi <simon.marchi@ericsson.com>
To: Eli Zaretskii <eliz@gnu.org>, Simon Marchi <simon.marchi@polymtl.ca>
Cc: <gdb-patches@sourceware.org>
Subject: Re: [PATCH] python doc: Rework Breakpoint.__init__ doc
Date: Fri, 08 Dec 2017 20:47:00 -0000 [thread overview]
Message-ID: <52711e30-004e-3a2c-d77c-e409a1f66d9e@ericsson.com> (raw)
In-Reply-To: <83vahhuhqo.fsf@gnu.org>
On 2017-12-08 02:44 PM, Eli Zaretskii wrote:
>> 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.
Ok.
>> 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").
Ok.
>>>> +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.
Ok, I don't think it's useful to say
This argument can be either @code{gdb.BP_BREAKPOINT} or @code{gdb.BP_WATCHPOINT}
since there are other acceptable values as well referring to the list below is better.
So I'll remove that, but keep
It defaults to @code{gdb.BP_BREAKPOINT}.
>>> 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.
I don't see the contradiction:
- don't use spec and function/line/label/source at the same time
- you should choose (exclusively) one form (the one that uses spec) or
the other (the one that uses function/line/label/source)
>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?
What do you mean, "produce the spec accordingly" ?
One indeed has to choose between the two forms. You can do
1.1 gdb.Breakpoint("main")
1.2 gdb.Breakpoint(spec="main")
1.3 gdb.Breakpoint(spec="-function main")
Those are all equivalent, and use the first form. spec is parsed as a
CLI-style linespec. If you want to use the second form, you can do:
2.1 gdb.Breakpoint(function="main")
The arguments of the second form are all keyword arguments, meaning that the
only way to pass a value to them is by naming them (such as the function= in
example 2.1).
However, showing two different constructors in the documentation is not technically
accurate with how it is implemented in the Python-support code, because it is
not possible to have two constructors with different signatures in Python.
Instead, we have a single constructor with all the parameters of both forms,
and validate that the user didn't mix arguments from both forms. But I thought
it was a good way of explaining how it was meant to be used.
Simon
next prev parent reply other threads:[~2017-12-08 20:47 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-12-07 21:23 Simon Marchi
2017-12-08 14:12 ` Eli Zaretskii
2017-12-08 18:00 ` Simon Marchi
2017-12-08 19:45 ` Eli Zaretskii
2017-12-08 20:47 ` Simon Marchi [this message]
2017-12-09 8:22 ` Eli Zaretskii
2017-12-12 21:16 ` Simon Marchi
2017-12-13 3:35 ` Eli Zaretskii
2017-12-13 4:54 ` Simon Marchi
2017-12-13 16:07 ` Eli Zaretskii
2017-12-13 16:29 ` Simon Marchi
2017-12-08 18:22 ` [PATCH v2] " Simon Marchi
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=52711e30-004e-3a2c-d77c-e409a1f66d9e@ericsson.com \
--to=simon.marchi@ericsson.com \
--cc=eliz@gnu.org \
--cc=gdb-patches@sourceware.org \
--cc=simon.marchi@polymtl.ca \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).