Re: [PATCH v5 00/20] Convert QAPI doc comments to generate rST instead of texinfo

[Markus Armbruster]

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.