From 1962bd39d567e8b44646e558b07b2742a5a61339 Mon Sep 17 00:00:00 2001 From: Marc-André Lureau Date: Thu, 13 Dec 2018 16:37:04 +0400 Subject: qapi: change enum visitor and gen_enum* to take QAPISchemaMember This will allow to add and access more properties associated with enum values/members, like the associated 'if' condition. We may want to have a specialized type QAPISchemaEnumMember, for now this will do. Modify gen_enum() and gen_enum_lookup() for the same reason. Suggested-by: Markus Armbruster Signed-off-by: Marc-André Lureau Reviewed-by: Markus Armbruster Message-Id: <20181213123724.4866-3-marcandre.lureau@redhat.com> Signed-off-by: Markus Armbruster --- scripts/qapi/doc.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts/qapi/doc.py') diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py index 987fd3c943..76cb186ff9 100755 --- a/scripts/qapi/doc.py +++ b/scripts/qapi/doc.py @@ -206,7 +206,7 @@ class QAPISchemaGenDocVisitor(qapi.common.QAPISchemaVisitor): def write(self, output_dir): self._gen.write(output_dir, self._prefix + 'qapi-doc.texi') - def visit_enum_type(self, name, info, ifcond, values, prefix): + def visit_enum_type(self, name, info, ifcond, members, prefix): doc = self.cur_doc self._gen.add(TYPE_FMT(type='Enum', name=doc.symbol, -- cgit v1.2.3-55-g7522 From a35c9bf82aff4e80a90f0adfc7383d03749db0b6 Mon Sep 17 00:00:00 2001 From: Marc-André Lureau Date: Thu, 13 Dec 2018 16:37:20 +0400 Subject: qapi: add 'If:' condition to enum values documentation Use a common function to generate the "If:..." line. While at it, get rid of the existing \n\n (no idea why it was there). Use a line-break in member description, this seems to look slightly better in the plaintext version. Signed-off-by: Marc-André Lureau Message-Id: <20181213123724.4866-19-marcandre.lureau@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- scripts/qapi/doc.py | 25 ++++++++++++++++--------- tests/qapi-schema/doc-good.json | 4 +++- tests/qapi-schema/doc-good.out | 1 + tests/qapi-schema/doc-good.texi | 2 +- 4 files changed, 21 insertions(+), 11 deletions(-) (limited to 'scripts/qapi/doc.py') diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py index 76cb186ff9..ab36b9dec6 100755 --- a/scripts/qapi/doc.py +++ b/scripts/qapi/doc.py @@ -126,19 +126,27 @@ def texi_body(doc): return texi_format(doc.body.text) -def texi_enum_value(value): +def texi_if(ifcond, prefix='\n', suffix='\n'): + """Format the #if condition""" + if not ifcond: + return '' + return '%s@b{If:} @code{%s}%s' % (prefix, ', '.join(ifcond), suffix) + + +def texi_enum_value(value, desc, suffix): """Format a table of members item for an enumeration value""" - return '@item @code{%s}\n' % value.name + return '@item @code{%s}\n%s%s' % ( + value.name, desc, texi_if(value.ifcond, prefix='@*')) -def texi_member(member, suffix=''): +def texi_member(member, desc, suffix): """Format a table of members item for an object type member""" typ = member.type.doc_type() membertype = ': ' + typ if typ else '' - return '@item @code{%s%s}%s%s\n' % ( + return '@item @code{%s%s}%s%s\n%s' % ( member.name, membertype, ' (optional)' if member.optional else '', - suffix) + suffix, desc) def texi_members(doc, what, base, variants, member_func): @@ -155,7 +163,7 @@ def texi_members(doc, what, base, variants, member_func): desc = 'One of ' + members_text + '\n' else: desc = 'Not documented\n' - items += member_func(section.member) + desc + items += member_func(section.member, desc, suffix='') if base: items += '@item The members of @code{%s}\n' % base.doc_type() if variants: @@ -165,7 +173,7 @@ def texi_members(doc, what, base, variants, member_func): if v.type.is_implicit(): assert not v.type.base and not v.type.variants for m in v.type.local_members: - items += member_func(m, when) + items += member_func(m, desc='', suffix=when) else: items += '@item The members of @code{%s}%s\n' % ( v.type.doc_type(), when) @@ -185,8 +193,7 @@ def texi_sections(doc, ifcond): body += texi_example(section.text) else: body += texi_format(section.text) - if ifcond: - body += '\n\n@b{If:} @code{%s}' % ", ".join(ifcond) + body += texi_if(ifcond, suffix='') return body diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 984cd8ed06..1cd4935710 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -55,7 +55,9 @@ # # @two is undocumented ## -{ 'enum': 'Enum', 'data': [ 'one', 'two' ], 'if': 'defined(IFCOND)' } +{ 'enum': 'Enum', 'data': + [ { 'name': 'one', 'if': 'defined(IFONE)' }, 'two' ], + 'if': 'defined(IFCOND)' } ## # @Base: diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index c2fc5c774a..53bd177f7d 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -11,6 +11,7 @@ enum QType module doc-good.json enum Enum member one + if ['defined(IFONE)'] member two if ['defined(IFCOND)'] object Base diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.texi index e42eace474..405055b146 100644 --- a/tests/qapi-schema/doc-good.texi +++ b/tests/qapi-schema/doc-good.texi @@ -84,12 +84,12 @@ Examples: @table @asis @item @code{one} The @emph{one} @{and only@} +@*@b{If:} @code{defined(IFONE)} @item @code{two} Not documented @end table @code{two} is undocumented - @b{If:} @code{defined(IFCOND)} @end deftp -- cgit v1.2.3-55-g7522 From 8867bf08087a3d508a0ecce661f7e430c1747022 Mon Sep 17 00:00:00 2001 From: Marc-André Lureau Date: Thu, 13 Dec 2018 16:37:21 +0400 Subject: qapi: add 'If:' condition to struct members documentation Signed-off-by: Marc-André Lureau Message-Id: <20181213123724.4866-20-marcandre.lureau@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- scripts/qapi/doc.py | 4 ++-- tests/qapi-schema/doc-good.json | 3 ++- tests/qapi-schema/doc-good.out | 1 + tests/qapi-schema/doc-good.texi | 1 + 4 files changed, 6 insertions(+), 3 deletions(-) (limited to 'scripts/qapi/doc.py') diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py index ab36b9dec6..b6f834b917 100755 --- a/scripts/qapi/doc.py +++ b/scripts/qapi/doc.py @@ -143,10 +143,10 @@ def texi_member(member, desc, suffix): """Format a table of members item for an object type member""" typ = member.type.doc_type() membertype = ': ' + typ if typ else '' - return '@item @code{%s%s}%s%s\n%s' % ( + return '@item @code{%s%s}%s%s\n%s%s' % ( member.name, membertype, ' (optional)' if member.optional else '', - suffix, desc) + suffix, desc, texi_if(member.ifcond, prefix='@*')) def texi_members(doc, what, base, variants, member_func): diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 1cd4935710..28992fc615 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -72,7 +72,8 @@ # # Another paragraph (but no @var: line) ## -{ 'struct': 'Variant1', 'data': { 'var1': 'str' } } +{ 'struct': 'Variant1', + 'data': { 'var1': { 'type': 'str', 'if': 'defined(IFSTR)' } } } ## # @Variant2: diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 53bd177f7d..4ab55683ce 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -18,6 +18,7 @@ object Base member base1: Enum optional=False object Variant1 member var1: str optional=False + if ['defined(IFSTR)'] object Variant2 object Object base Base diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.texi index 405055b146..f87f9faacb 100644 --- a/tests/qapi-schema/doc-good.texi +++ b/tests/qapi-schema/doc-good.texi @@ -119,6 +119,7 @@ Another paragraph (but no @code{var}: line) @table @asis @item @code{var1: string} Not documented +@*@b{If:} @code{defined(IFSTR)} @end table @end deftp -- cgit v1.2.3-55-g7522 From 01ae9cc2544f03299bb8b9923dec5da3d94f7c57 Mon Sep 17 00:00:00 2001 From: Marc-André Lureau Date: Thu, 13 Dec 2018 16:37:22 +0400 Subject: qapi: add condition to variants documentation Signed-off-by: Marc-André Lureau Message-Id: <20181213123724.4866-21-marcandre.lureau@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- scripts/qapi/doc.py | 4 ++-- tests/qapi-schema/doc-good.json | 4 ++-- tests/qapi-schema/doc-good.out | 3 +++ tests/qapi-schema/doc-good.texi | 4 ++-- 4 files changed, 9 insertions(+), 6 deletions(-) (limited to 'scripts/qapi/doc.py') diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py index b6f834b917..c03b690161 100755 --- a/scripts/qapi/doc.py +++ b/scripts/qapi/doc.py @@ -168,8 +168,8 @@ def texi_members(doc, what, base, variants, member_func): items += '@item The members of @code{%s}\n' % base.doc_type() if variants: for v in variants.variants: - when = ' when @code{%s} is @t{"%s"}' % ( - variants.tag_member.name, v.name) + when = ' when @code{%s} is @t{"%s"}%s' % ( + variants.tag_member.name, v.name, texi_if(v.ifcond, " (", ")")) if v.type.is_implicit(): assert not v.type.base and not v.type.variants for m in v.type.local_members: diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 28992fc615..f7fb48af38 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -86,13 +86,13 @@ { 'union': 'Object', 'base': 'Base', 'discriminator': 'base1', - 'data': { 'one': 'Variant1', 'two': 'Variant2' } } + 'data': { 'one': 'Variant1', 'two': { 'type': 'Variant2', 'if': 'IFTWO' } } } ## # @SugaredUnion: ## { 'union': 'SugaredUnion', - 'data': { 'one': 'Variant1', 'two': 'Variant2' } } + 'data': { 'one': 'Variant1', 'two': { 'type': 'Variant2', 'if': 'IFTWO' } } } ## # == Another subsection diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 4ab55683ce..21bf345ff0 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -25,6 +25,7 @@ object Object tag base1 case one: Variant1 case two: Variant2 + if ['IFTWO'] object q_obj_Variant1-wrapper member data: Variant1 optional=False object q_obj_Variant2-wrapper @@ -32,11 +33,13 @@ object q_obj_Variant2-wrapper enum SugaredUnionKind member one member two + if ['IFTWO'] object SugaredUnion member type: SugaredUnionKind optional=False tag type case one: q_obj_Variant1-wrapper case two: q_obj_Variant2-wrapper + if ['IFTWO'] object q_obj_cmd-arg member arg1: int optional=False member arg2: str optional=True diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.texi index f87f9faacb..2526abc6d9 100644 --- a/tests/qapi-schema/doc-good.texi +++ b/tests/qapi-schema/doc-good.texi @@ -142,7 +142,7 @@ Not documented @table @asis @item The members of @code{Base} @item The members of @code{Variant1} when @code{base1} is @t{"one"} -@item The members of @code{Variant2} when @code{base1} is @t{"two"} +@item The members of @code{Variant2} when @code{base1} is @t{"two"} (@b{If:} @code{IFTWO}) @end table @end deftp @@ -158,7 +158,7 @@ Not documented @item @code{type} One of @t{"one"}, @t{"two"} @item @code{data: Variant1} when @code{type} is @t{"one"} -@item @code{data: Variant2} when @code{type} is @t{"two"} +@item @code{data: Variant2} when @code{type} is @t{"two"} (@b{If:} @code{IFTWO}) @end table @end deftp -- cgit v1.2.3-55-g7522