Re: [Qemu-devel] [PATCH for-2.9 26/47] qapi2texi: Generate reference to base type members

[Eric Blake]

On 03/15/2017 02:30 AM, Markus Armbruster wrote:
> Eric Blake <address@hidden> writes:
> 

>>> @@ -152,6 +152,8 @@ def texi_members(doc, what, member_func):
>>>          else:
>>>              desc = 'Not documented'
>>>          items += member_func(section.member) + texi_format(desc) + '\n'
>>> +    if base:
>>> +        items += '@item The members of @code{%s}\n' % base.doc_type()
>>
>> Will this still work for implicit bases?
>>
>>>  
>>> @@ -205,11 +207,13 @@ class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor):
>>>              typ = 'Flat Union'
>>>          else:
>>>              typ = 'Simple Union'
>>> +        if base and base.is_implicit():
>>> +            base = None
>>
>> Hmm - you just ignore those, such as the anonymous base in CpuInfo.  On
>> the other hand, CpuInfo documents its base fields explicitly.  Are we at
>> risk of double-documenting a base member, both explicitly and via its
>> named base type?
> 
> Actually no.
> 
> Doc comments should document exactly the members defined locally.  This
> includes members of anonymous bases, but not members of named bases.  If
> you try to document members of named basses, you get your wrist slapped.

Cool, we enforce a uniform style.  That's what I was missing.

>> At any rate, this patch is an incremental improvement, so:
>> Reviewed-by: Eric Blake <address@hidden>

And you've shown me that we don't even need a followup for my original
concern.

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

signature.asc
Description: OpenPGP digital signature