[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v5 00/20] Convert QAPI doc comments to generate rST instead o
From: |
Markus Armbruster |
Subject: |
Re: [PATCH v5 00/20] Convert QAPI doc comments to generate rST instead of texinfo |
Date: |
Fri, 04 Sep 2020 17:54:18 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) |
Peter Maydell <peter.maydell@linaro.org> writes:
> On Fri, 4 Sep 2020 at 15:34, Markus Armbruster <armbru@redhat.com> wrote:
>> Peter Maydell <peter.maydell@linaro.org> writes:
>> > I'm not sure whether the scripts/qapi code supports telling
>> > a consumer of the parsed info about this -- is it sufficient
>> > for QAPISchemaGenRSTVisitor to implement the 'visit_include'
>> > method, find the path to the included .qapi file from the
>> > arguments and call Sphinx's env.notedependency(), or do we
>> > need to do something more complicated to get the list of
>> > all the included .qapi files ?
>>
>> Visitors can implement visit_include() to see include directives.
>> QAPISchemaModularCVisitor does, to generate #include that mirror the
>> source schema. This is not what your want.
>
> Why not? Surely "see include directives" is exactly what I want?
> Any time the QAPI parser opens a file that's different from the
> initial one we want to know about it.
>
>> You want visit_module(). The appended hack makes qapi-gen.py spit out
>> the modules when it generates types, e.g.:
>>
>> $ python3 -B scripts/qapi-gen.py -o scratch
>> tests/qapi-schema/qapi-schema-test.json
>> ### None
>> ### 'qapi-schema-test.json'
>> ### 'include/sub-module.json'
>> ### 'sub-sub-module.json'
>
> What's a "module" here ?
Initially, the include directive was just that: include another file's
contents right here.
Back in 2018, we switched from generating monolithic code to generating
modular code. What does that mean?
Instead of generating the kitchen sink into a single qapi-types.c, we
split out the stuff generated for each FOO.json included by
qapi-schema.json into qapi-types-FOO.c.
Same for qapi-types.h, but with #include stitching that mirrors the
schema's include directives. So, if FOO.json includes SUB.json, then
qapi-types-FOO.h will include qapi-types-SUB.h.
Same for qapi-{commands,events,visit}.{c,h}.
The qapi-schema.json (rather: the file you pass to qapi-gen.py) is the
main module.
The .json it includes are the sub-modules.
visit_module() lets you see the modules.
visit_include() lets you see the includes. The same module can be
included multiple times. Having to filter that out would be annoying.
> Does this still produce output if the
> top level .json file includes a sub-json file that doesn't actually
> have any contents ? (We still want to generate the dependency
> then, so we update the docs if the included file is edited to
> add content.)
If it doesn't, I'd be willing to call it a bug. I dimly remember fixing
this (or a similar bug) before.