[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v6 17/21] docs/devel/qapi-code-gen.txt: Update to new rST bac
From: |
Markus Armbruster |
Subject: |
Re: [PATCH v6 17/21] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions |
Date: |
Tue, 29 Sep 2020 15:27:12 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) |
Peter Maydell <peter.maydell@linaro.org> writes:
> On Tue, 29 Sep 2020 at 13:35, Markus Armbruster <armbru@redhat.com> wrote:
>>
>> Peter Maydell <peter.maydell@linaro.org> writes:
>>
>> > Update the documentation of QAPI document comment syntax to match
>> > the new rST backend requirements. The principal changes are:
>> > * whitespace is now significant,
>>
>> Well, differently significant :) Anyway, close enough.
>>
>> > and multiline definitions
>> > must have their second and subsequent lines indented to
>> > match the first line
>> > * general rST format markup is permitted, not just the small
>> > set of markup the old texinfo generator handled. For most
>> > things (notably bulleted and itemized lists) the old format
>> > is the same as rST was.
>>
>> "was the same as rST is"?
>
> Yes :-)
Can fix in my tree.
>
>> v5 had
>>
>> @@ -899,6 +915,12 @@ commands and events), member (for structs and
>> unions), branch (for
>> alternates), or value (for enums), and finally optional tagged
>> sections.
>>
>> +Descriptions of arguments can span multiple lines; if they
>> +do then the second and subsequent lines must be indented
>> +to line up with the first character of the first line of the
>> +description. The parser will report a syntax error if there
>> +is insufficient indentation.
>> +
>> FIXME: the parser accepts these things in almost any order.
>> FIXME: union branches should be described, too.
>>
>> I questioned the value of the last sentence. You dropped both.
>> Intentional?
>
> I moved the first sentence to patch 5 in v6 (ie to the patch
> which updates parser.py to enforce those indentation restrictions),
> so as to make patches 1..5 suitable for merging even if we needed
> to respin the second half of the series.
I see.
>> > @@ -937,6 +950,16 @@ multiline argument descriptions.
>> > A 'Since: x.y.z' tagged section lists the release that introduced the
>> > definition.
>> >
>> > +The text of a section can start on a new line, in
>> > +which case it must not be indented at all. It can also start
>> > +on the same line as the 'Note:', 'Returns:', etc tag. In this
>> > +case if it spans multiple lines then second and subsequent
>> > +lines must be indented to match the first.
>
> I also moved this paragraph into patch 5 (where it appears just
> above the "A 'Since:..." text you can see in the context here)
> but forgot to delete the copy of it here, so at this point it is
> duplicate text and should not be in this patch. Oops.
>
>> > +
>> > +An 'Example' or 'Examples' section is automatically rendered
>> > +entirely as literal fixed-width text. In other sections,
>> > +the text is formatted, and rST markup can be used.
>
> (This patch is the right place for this paragraph.)
Thanks!
Reviewed-by: Markus Armbruster <armbru@redhat.com>
- [PATCH v6 10/21] qapi: Use rST markup for literal blocks, (continued)
- [PATCH v6 10/21] qapi: Use rST markup for literal blocks, Peter Maydell, 2020/09/25
- [PATCH v6 20/21] configure: Drop texinfo requirement, Peter Maydell, 2020/09/25
- [PATCH v6 12/21] tests/qapi-schema: Convert doc-good.json to rST-style strong/emphasis, Peter Maydell, 2020/09/25
- [PATCH v6 13/21] meson.build: Move SPHINX_ARGS to top level meson.build file, Peter Maydell, 2020/09/25
- [PATCH v6 17/21] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions, Peter Maydell, 2020/09/25
- [PATCH v6 16/21] scripts/qapi: Remove texinfo generation support, Peter Maydell, 2020/09/25
- [PATCH v6 18/21] scripts/texi2pod: Delete unused script, Peter Maydell, 2020/09/25
- [PATCH v6 19/21] Remove Texinfo related line from git.orderfile, Peter Maydell, 2020/09/25
- [PATCH v6 21/21] Remove texinfo dependency from docker and CI configs, Peter Maydell, 2020/09/25
- Re: [PATCH v6 00/21] Convert QAPI doc comments to generate rST instead of texinfo, John Snow, 2020/09/25