On 03/15/2017 02:30 AM, Markus Armbruster wrote: > Eric Blake <ebl...@redhat.com> 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 <ebl...@redhat.com>
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
