Re: [Qemu-devel] [PATCH for-2.9 16/47] qapi2texi: Convert to QAPISchemaVisitor

[Markus Armbruster]

Eric Blake <address@hidden> writes:

> On 03/13/2017 01:18 AM, Markus Armbruster wrote:
>> qapi2texi works with schema expression trees.  Such a tight coupling
>> to schema language syntax is not a good idea.  Convert it to the visitor
>> interface the other generators use.
>> 
>> No change to generated documentation.
>> 
>> Signed-off-by: Markus Armbruster <address@hidden>
>> ---
>>  scripts/qapi2texi.py | 228 
>> ++++++++++++++++++++++++++-------------------------
>>  1 file changed, 118 insertions(+), 110 deletions(-)
>> 
>
>> +    def visit_object_type(self, name, info, base, members, variants):
>> +        doc = self.cur_doc
>> +        if not variants:
>> +            typ = 'Struct'
>> +        elif variants._tag_name:        # TODO unclean member access
>> +            typ = 'Flat Union'
>> +        else:
>> +            typ = 'Simple Union'
>
> Do we even want to document this distinction to the end user?

No, we don't.  '[PATCH for-2.9 29/47] qapi2texi: Use category "Object"
for all object types' takes care of it.

> Introspection managed to hide the difference by introducing the
> appropriate generated wrapper types that demonstrate the additional {}
> nesting in a way compatible with rewriting simple unions into flat
> unions.  If we don't explain the difference here, we can get rid of the
> unclean member access, but then again risk documentation that is not
> clear whether {} nesting is needed.
>
> I guess there's also the fact that for this patch, you intentionally
> tried to make no difference to the generated docs (good); so any tweaks
> to union output should be later patches anyways.
>
> Reviewed-by: Eric Blake <address@hidden>

Thanks!