| Message ID | 1489385927-6735-27-git-send-email-armbru@redhat.com |
|---|---|
| State | New |
| Headers | show |
On 03/13/2017 01:18 AM, Markus Armbruster wrote: > The generated documentation doesn't mention object type members > inherited from a base type. Fix that. > > Example change (qemu-qmp-ref.txt): > > -- Struct: VncServerInfo > > The network connection information for server > > Members: > 'auth' (optional) > authentication method used for the plain (non-websocket) VNC > server > + The members of 'VncBasicInfo' > Again, will be more useful later in the series when you add hyperlinking. > Since: 2.1 > > Signed-off-by: Markus Armbruster <armbru@redhat.com> > --- > scripts/qapi2texi.py | 12 ++++++++---- > 1 file changed, 8 insertions(+), 4 deletions(-) > Reviewed-by: Eric Blake <eblake@redhat.com> > diff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py > index 993b652..7083d0c 100755 > --- a/scripts/qapi2texi.py > +++ b/scripts/qapi2texi.py > @@ -143,7 +143,7 @@ def texi_member(member): > ' (optional)' if member.optional else '') > > > -def texi_members(doc, what, member_func): > +def texi_members(doc, what, base, member_func): > """Format the table of members""" > items = '' > for section in doc.args.itervalues(): > @@ -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? At any rate, this patch is an incremental improvement, so: Reviewed-by: Eric Blake <eblake@redhat.com>
Eric Blake <eblake@redhat.com> writes: > On 03/13/2017 01:18 AM, Markus Armbruster wrote: >> The generated documentation doesn't mention object type members >> inherited from a base type. Fix that. >> >> Example change (qemu-qmp-ref.txt): >> >> -- Struct: VncServerInfo >> >> The network connection information for server >> >> Members: >> 'auth' (optional) >> authentication method used for the plain (non-websocket) VNC >> server >> + The members of 'VncBasicInfo' >> > > Again, will be more useful later in the series when you add hyperlinking. > >> Since: 2.1 >> >> Signed-off-by: Markus Armbruster <armbru@redhat.com> >> --- >> scripts/qapi2texi.py | 12 ++++++++---- >> 1 file changed, 8 insertions(+), 4 deletions(-) >> > > Reviewed-by: Eric Blake <eblake@redhat.com> > >> diff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py >> index 993b652..7083d0c 100755 >> --- a/scripts/qapi2texi.py >> +++ b/scripts/qapi2texi.py >> @@ -143,7 +143,7 @@ def texi_member(member): >> ' (optional)' if member.optional else '') >> >> >> -def texi_members(doc, what, member_func): >> +def texi_members(doc, what, base, member_func): >> """Format the table of members""" >> items = '' >> for section in doc.args.itervalues(): >> @@ -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. For example, if I do diff --git a/qapi-schema.json b/qapi-schema.json index 1d7b1cd..4214e97 100644 --- a/qapi-schema.json +++ b/qapi-schema.json @@ -1549,6 +1549,7 @@ # # @auth: authentication method used for # the plain (non-websocket) VNC server +# @family: address family # # Since: 2.1 ## I get qemu/qapi-schema.json:1545: The following documented members are not in the declaration: family > At any rate, this patch is an incremental improvement, so: > Reviewed-by: Eric Blake <eblake@redhat.com> Thanks!
On 03/15/2017 02:30 AM, Markus Armbruster wrote: > Eric Blake <eblake@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 <eblake@redhat.com> And you've shown me that we don't even need a followup for my original concern.
diff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py index 993b652..7083d0c 100755 --- a/scripts/qapi2texi.py +++ b/scripts/qapi2texi.py @@ -143,7 +143,7 @@ def texi_member(member): ' (optional)' if member.optional else '') -def texi_members(doc, what, member_func): +def texi_members(doc, what, base, member_func): """Format the table of members""" items = '' for section in doc.args.itervalues(): @@ -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() if not items: return '' return '\n@b{%s:}\n@table @asis\n%s@end table\n' % (what, items) @@ -174,9 +176,9 @@ def texi_sections(doc): return body -def texi_entity(doc, what, member_func=texi_member): +def texi_entity(doc, what, base=None, member_func=texi_member): return (texi_body(doc) - + texi_members(doc, what, member_func) + + texi_members(doc, what, base, member_func) + texi_sections(doc)) @@ -205,11 +207,13 @@ class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor): typ = 'Flat Union' else: typ = 'Simple Union' + if base and base.is_implicit(): + base = None if self.out: self.out += '\n' self.out += TYPE_FMT(type=typ, name=doc.symbol, - body=texi_entity(doc, 'Members')) + body=texi_entity(doc, 'Members', base)) def visit_alternate_type(self, name, info, variants): doc = self.cur_doc
The generated documentation doesn't mention object type members inherited from a base type. Fix that. Example change (qemu-qmp-ref.txt): -- Struct: VncServerInfo The network connection information for server Members: 'auth' (optional) authentication method used for the plain (non-websocket) VNC server + The members of 'VncBasicInfo' Since: 2.1 Signed-off-by: Markus Armbruster <armbru@redhat.com> --- scripts/qapi2texi.py | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-)