From c6a1a98b4222114fbebbb40814ba765ac4530937 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Mon, 2 Oct 2017 16:13:31 +0200 Subject: [PATCH 01/13] qapi-schema: Fix query-vm-generation-id's doc comment markup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reported-by: Daniel P. Berrange Signed-off-by: Markus Armbruster Message-Id: <20171002141341.24616-2-armbru@redhat.com> Reviewed-by: Marc-André Lureau --- qapi-schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qapi-schema.json b/qapi-schema.json index 18457954a8..ea3723f903 100644 --- a/qapi-schema.json +++ b/qapi-schema.json @@ -3188,7 +3188,7 @@ # # Show Virtual Machine Generation ID # -# Since 2.9 +# Since: 2.9 ## { 'command': 'query-vm-generation-id', 'returns': 'GuidInfo' } From 67ab1ce9263f77b352faea1104f0ebc2e50a3d42 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Mon, 2 Oct 2017 16:13:32 +0200 Subject: [PATCH 02/13] qapi: Stop rejecting #optional MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Commit 1d8bda1 got rid of #optional tags, and added a check to keep them from getting added back, to make sure patches then in flight don't add them back. It's been six months, time to drop that check. Signed-off-by: Markus Armbruster Message-Id: <20171002141341.24616-3-armbru@redhat.com> Reviewed-by: Marc-André Lureau --- scripts/qapi.py | 4 ---- 1 file changed, 4 deletions(-) diff --git a/scripts/qapi.py b/scripts/qapi.py index 62dc52ed6e..dc92bca620 100644 --- a/scripts/qapi.py +++ b/scripts/qapi.py @@ -234,10 +234,6 @@ class QAPIDoc(object): raise QAPIParseError(self.parser, "'%s' not allowed in free-form documentation" % match.group(1)) - # TODO Drop this once the dust has settled - if (isinstance(self.section, QAPIDoc.ArgSection) - and '#optional' in line): - raise QAPISemError(self.info, "Please drop the #optional tag") self.section.append(line) def connect_member(self, member): From 2281d00c3d75e684d9c0051169a6ac1cc60b66cd Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Mon, 2 Oct 2017 16:13:33 +0200 Subject: [PATCH 03/13] qapi: Eliminate QAPISchemaParser.__init__()'s local fname MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Markus Armbruster Message-Id: <20171002141341.24616-4-armbru@redhat.com> Reviewed-by: Marc-André Lureau --- scripts/qapi.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/scripts/qapi.py b/scripts/qapi.py index dc92bca620..6c8001e96d 100644 --- a/scripts/qapi.py +++ b/scripts/qapi.py @@ -261,8 +261,7 @@ class QAPISchemaParser(object): def __init__(self, fp, previously_included=[], incl_info=None): abs_fname = os.path.abspath(fp.name) - fname = fp.name - self.fname = fname + self.fname = fp.name previously_included.append(abs_fname) self.incl_info = incl_info self.src = fp.read() @@ -277,7 +276,7 @@ class QAPISchemaParser(object): self.accept() while self.tok is not None: - info = {'file': fname, 'line': self.line, + info = {'file': self.fname, 'line': self.line, 'parent': self.incl_info} if self.tok == '#': self.reject_expr_doc() From 64d6033b203b32f02d0986220af5dc3cd1301ba6 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Mon, 2 Oct 2017 16:13:34 +0200 Subject: [PATCH 04/13] qapi: Make cur_doc local to QAPISchemaParser.__init__() MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit QAPISchemaParser.cur_doc is used only by .__init__() and its helper .reject_expr_doc(). Make it local to __init__() and pass it to .reject_expr_doc() explicitly. Signed-off-by: Markus Armbruster Message-Id: <20171002141341.24616-5-armbru@redhat.com> Reviewed-by: Marc-André Lureau --- scripts/qapi.py | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/scripts/qapi.py b/scripts/qapi.py index 6c8001e96d..2f2738f562 100644 --- a/scripts/qapi.py +++ b/scripts/qapi.py @@ -272,21 +272,21 @@ class QAPISchemaParser(object): self.line_pos = 0 self.exprs = [] self.docs = [] - self.cur_doc = None self.accept() + cur_doc = None while self.tok is not None: info = {'file': self.fname, 'line': self.line, 'parent': self.incl_info} if self.tok == '#': - self.reject_expr_doc() - self.cur_doc = self.get_doc(info) - self.docs.append(self.cur_doc) + self.reject_expr_doc(cur_doc) + cur_doc = self.get_doc(info) + self.docs.append(cur_doc) continue expr = self.get_expr(False) if 'include' in expr: - self.reject_expr_doc() + self.reject_expr_doc(cur_doc) if len(expr) != 1: raise QAPISemError(info, "Invalid 'include' directive") include = expr['include'] @@ -296,7 +296,7 @@ class QAPISchemaParser(object): self._include(include, info, os.path.dirname(abs_fname), previously_included) elif "pragma" in expr: - self.reject_expr_doc() + self.reject_expr_doc(cur_doc) if len(expr) != 1: raise QAPISemError(info, "Invalid 'pragma' directive") pragma = expr['pragma'] @@ -308,22 +308,22 @@ class QAPISchemaParser(object): else: expr_elem = {'expr': expr, 'info': info} - if self.cur_doc: - if not self.cur_doc.symbol: + if cur_doc: + if not cur_doc.symbol: raise QAPISemError( - self.cur_doc.info, - "Expression documentation required") - expr_elem['doc'] = self.cur_doc + cur_doc.info, "Expression documentation required") + expr_elem['doc'] = cur_doc self.exprs.append(expr_elem) - self.cur_doc = None - self.reject_expr_doc() + cur_doc = None + self.reject_expr_doc(cur_doc) - def reject_expr_doc(self): - if self.cur_doc and self.cur_doc.symbol: + @staticmethod + def reject_expr_doc(doc): + if doc and doc.symbol: raise QAPISemError( - self.cur_doc.info, + doc.info, "Documentation for '%s' is not followed by the definition" - % self.cur_doc.symbol) + % doc.symbol) def _include(self, include, info, base_dir, previously_included): incl_abs_fname = os.path.join(base_dir, include) From cfa438ff53937c78c9a0e50b4b774ea5a6430710 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Mon, 2 Oct 2017 16:13:35 +0200 Subject: [PATCH 05/13] tests/qapi-schema/doc-bad-section: New, factored out of doc-good MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A negative test case crept into doc-good.json: invalid use of section markup we currently fail to reject. Move this into its own doc-bad-section.json. Signed-off-by: Markus Armbruster Message-Id: <20171002141341.24616-6-armbru@redhat.com> Reviewed-by: Marc-André Lureau --- tests/Makefile.include | 3 ++- tests/qapi-schema/doc-bad-section.err | 0 tests/qapi-schema/doc-bad-section.exit | 1 + tests/qapi-schema/doc-bad-section.json | 11 +++++++++++ tests/qapi-schema/doc-bad-section.out | 13 +++++++++++++ tests/qapi-schema/doc-good.json | 1 - tests/qapi-schema/doc-good.out | 2 +- tests/qapi-schema/doc-good.texi | 2 +- 8 files changed, 29 insertions(+), 4 deletions(-) create mode 100644 tests/qapi-schema/doc-bad-section.err create mode 100644 tests/qapi-schema/doc-bad-section.exit create mode 100644 tests/qapi-schema/doc-bad-section.json create mode 100644 tests/qapi-schema/doc-bad-section.out diff --git a/tests/Makefile.include b/tests/Makefile.include index b4bcc872f2..f8e20d9f5d 100644 --- a/tests/Makefile.include +++ b/tests/Makefile.include @@ -416,6 +416,7 @@ qapi-schema += command-int.json qapi-schema += comments.json qapi-schema += doc-bad-alternate-member.json qapi-schema += doc-bad-command-arg.json +qapi-schema += doc-bad-section.json qapi-schema += doc-bad-symbol.json qapi-schema += doc-bad-union-member.json qapi-schema += doc-before-include.json @@ -433,10 +434,10 @@ qapi-schema += doc-invalid-end2.json qapi-schema += doc-invalid-return.json qapi-schema += doc-invalid-section.json qapi-schema += doc-invalid-start.json -qapi-schema += doc-missing.json qapi-schema += doc-missing-colon.json qapi-schema += doc-missing-expr.json qapi-schema += doc-missing-space.json +qapi-schema += doc-missing.json qapi-schema += doc-no-symbol.json qapi-schema += double-data.json qapi-schema += double-type.json diff --git a/tests/qapi-schema/doc-bad-section.err b/tests/qapi-schema/doc-bad-section.err new file mode 100644 index 0000000000..e69de29bb2 diff --git a/tests/qapi-schema/doc-bad-section.exit b/tests/qapi-schema/doc-bad-section.exit new file mode 100644 index 0000000000..573541ac97 --- /dev/null +++ b/tests/qapi-schema/doc-bad-section.exit @@ -0,0 +1 @@ +0 diff --git a/tests/qapi-schema/doc-bad-section.json b/tests/qapi-schema/doc-bad-section.json new file mode 100644 index 0000000000..560df4b087 --- /dev/null +++ b/tests/qapi-schema/doc-bad-section.json @@ -0,0 +1,11 @@ +# = section within an expression comment +# BUG: not rejected + +## +# @Enum: +# == Produces *invalid* texinfo +# @one: The _one_ {and only} +# +# @two is undocumented +## +{ 'enum': 'Enum', 'data': [ 'one', 'two' ] } diff --git a/tests/qapi-schema/doc-bad-section.out b/tests/qapi-schema/doc-bad-section.out new file mode 100644 index 0000000000..6fce84dd34 --- /dev/null +++ b/tests/qapi-schema/doc-bad-section.out @@ -0,0 +1,13 @@ +enum Enum ['one', 'two'] +enum QType ['none', 'qnull', 'qnum', 'qstring', 'qdict', 'qlist', 'qbool'] + prefix QTYPE +object q_empty +doc symbol=Enum + body= +== Produces *invalid* texinfo + arg=one +The _one_ {and only} + arg=two + + section= +@two is undocumented diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index cfdc0a8a81..97ab4625ff 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -51,7 +51,6 @@ ## # @Enum: -# == Produces *invalid* texinfo # @one: The _one_ {and only} # # @two is undocumented diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 63ca25a8b9..c55e394e8a 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -77,7 +77,7 @@ Examples: - {braces} doc symbol=Enum body= -== Produces *invalid* texinfo + arg=one The _one_ {and only} arg=two diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.texi index c410626e4a..a331349756 100644 --- a/tests/qapi-schema/doc-good.texi +++ b/tests/qapi-schema/doc-good.texi @@ -76,7 +76,7 @@ Examples: @deftp {Enum} Enum -@subsection Produces @strong{invalid} texinfo + @b{Values:} @table @asis From 0968dc9ae4d3f309c4ab4bddc2a69c8d9b2786ae Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Mon, 2 Oct 2017 16:13:36 +0200 Subject: [PATCH 06/13] qapi2texi: Clean up texi_sections() MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Repurposing the function parameter doc for stepping through doc.sections.__str__() is not nice. Use new variable @text instead. While there, eliminate variables name and func. Signed-off-by: Markus Armbruster Message-Id: <20171002141341.24616-7-armbru@redhat.com> Reviewed-by: Marc-André Lureau --- scripts/qapi2texi.py | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py index a317526e51..f876d9a174 100755 --- a/scripts/qapi2texi.py +++ b/scripts/qapi2texi.py @@ -180,16 +180,14 @@ def texi_sections(doc): """Format additional sections following arguments""" body = '' for section in doc.sections: - name, doc = (section.name, str(section)) - func = texi_format - if name.startswith('Example'): - func = texi_example - - if name: + if section.name: # prefer @b over @strong, so txt doesn't translate it to *Foo:* - body += '\n\n@b{%s:}\n' % name - - body += func(doc) + body += '\n\n@b{%s:}\n' % section.name + text = str(section) + if section.name.startswith('Example'): + body += texi_example(text) + else: + body += texi_format(text) return body From fc3f0df18711121ddbcd04bac3a6abb3fb9392be Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Mon, 2 Oct 2017 16:13:37 +0200 Subject: [PATCH 07/13] qapi: Unify representation of doc section without name MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit We have two representations of sections without a name: the main section uses name=None, the others name=''. Standardize on name=None. Signed-off-by: Markus Armbruster Message-Id: <20171002141341.24616-8-armbru@redhat.com> Reviewed-by: Marc-André Lureau --- scripts/qapi.py | 2 +- scripts/qapi2texi.py | 2 +- tests/qapi-schema/doc-bad-section.out | 2 +- tests/qapi-schema/doc-good.out | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/scripts/qapi.py b/scripts/qapi.py index 2f2738f562..2137067b48 100644 --- a/scripts/qapi.py +++ b/scripts/qapi.py @@ -204,7 +204,7 @@ class QAPIDoc(object): self.section = QAPIDoc.ArgSection(name) self.args[name] = self.section - def _start_section(self, name=''): + def _start_section(self, name=None): if name in ('Returns', 'Since') and self.has_section(name): raise QAPIParseError(self.parser, "Duplicated '%s' section" % name) diff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py index f876d9a174..f16fa1ba53 100755 --- a/scripts/qapi2texi.py +++ b/scripts/qapi2texi.py @@ -184,7 +184,7 @@ def texi_sections(doc): # prefer @b over @strong, so txt doesn't translate it to *Foo:* body += '\n\n@b{%s:}\n' % section.name text = str(section) - if section.name.startswith('Example'): + if section.name and section.name.startswith('Example'): body += texi_example(text) else: body += texi_format(text) diff --git a/tests/qapi-schema/doc-bad-section.out b/tests/qapi-schema/doc-bad-section.out index 6fce84dd34..089bde1381 100644 --- a/tests/qapi-schema/doc-bad-section.out +++ b/tests/qapi-schema/doc-bad-section.out @@ -9,5 +9,5 @@ doc symbol=Enum The _one_ {and only} arg=two - section= + section=None @two is undocumented diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index c55e394e8a..1d2c250527 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -82,7 +82,7 @@ doc symbol=Enum The _one_ {and only} arg=two - section= + section=None @two is undocumented doc symbol=Base body= From 09331fced1c4e04109ccc9d6852f29e0453cf583 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Mon, 2 Oct 2017 16:13:38 +0200 Subject: [PATCH 08/13] qapi: Simplify representation of QAPIDoc section text MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Use a string instead of a list of strings. This makes qapi2texi.py generate additional blank lines. They're harmless, and the next commit will get rid of them again. Signed-off-by: Markus Armbruster Message-Id: <20171002141341.24616-9-armbru@redhat.com> Reviewed-by: Marc-André Lureau --- scripts/qapi.py | 16 ++++++---------- scripts/qapi2texi.py | 14 +++++++------- tests/qapi-schema/doc-good.texi | 1 + tests/qapi-schema/test-qapi.py | 6 +++--- 4 files changed, 17 insertions(+), 20 deletions(-) diff --git a/scripts/qapi.py b/scripts/qapi.py index 2137067b48..e338868a52 100644 --- a/scripts/qapi.py +++ b/scripts/qapi.py @@ -106,13 +106,10 @@ class QAPIDoc(object): # optional section name (argument/member or section name) self.name = name # the list of lines for this section - self.content = [] + self.text = '' def append(self, line): - self.content.append(line) - - def __repr__(self): - return '\n'.join(self.content).strip() + self.text += line.rstrip() + '\n' class ArgSection(Section): def __init__(self, name): @@ -160,7 +157,7 @@ class QAPIDoc(object): # recognized, and get silently treated as ordinary text if self.symbol: self._append_symbol_line(line) - elif not self.body.content and line.startswith('@'): + elif not self.body.text and line.startswith('@'): if not line.endswith(':'): raise QAPIParseError(self.parser, "Line should end with :") self.symbol = line[1:-1] @@ -214,16 +211,15 @@ class QAPIDoc(object): def _end_section(self): if self.section: - contents = str(self.section) - if self.section.name and (not contents or contents.isspace()): + text = self.section.text = self.section.text.strip() + if self.section.name and (not text or text.isspace()): raise QAPIParseError(self.parser, "Empty doc section '%s'" % self.section.name) self.section = None def _append_freeform(self, line): in_arg = isinstance(self.section, QAPIDoc.ArgSection) - if (in_arg and self.section.content - and not self.section.content[-1] + if (in_arg and self.section.text.endswith('\n\n') and line and not line[0].isspace()): self._start_section() if (in_arg or not self.section.name diff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py index f16fa1ba53..379d27643d 100755 --- a/scripts/qapi2texi.py +++ b/scripts/qapi2texi.py @@ -125,7 +125,7 @@ def texi_format(doc): def texi_body(doc): """Format the main documentation body""" - return texi_format(str(doc.body)) + '\n' + return texi_format(doc.body.text) + '\n' def texi_enum_value(value): @@ -149,8 +149,8 @@ def texi_members(doc, what, base, variants, member_func): items = '' for section in doc.args.itervalues(): # TODO Drop fallbacks when undocumented members are outlawed - if section.content: - desc = texi_format(str(section)) + if section.text: + desc = texi_format(section.text) elif (variants and variants.tag_member == section.member and not section.member.type.doc_type()): values = section.member.type.member_names() @@ -183,11 +183,10 @@ def texi_sections(doc): if section.name: # prefer @b over @strong, so txt doesn't translate it to *Foo:* body += '\n\n@b{%s:}\n' % section.name - text = str(section) if section.name and section.name.startswith('Example'): - body += texi_example(text) + body += texi_example(section.text) else: - body += texi_format(text) + body += texi_format(section.text) return body @@ -240,7 +239,8 @@ class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor): self.out += '\n' if boxed: body = texi_body(doc) - body += '\n@b{Arguments:} the members of @code{%s}' % arg_type.name + body += ('\n@b{Arguments:} the members of @code{%s}\n' + % arg_type.name) body += texi_sections(doc) else: body = texi_entity(doc, 'Arguments') diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.texi index a331349756..c032f23fc1 100644 --- a/tests/qapi-schema/doc-good.texi +++ b/tests/qapi-schema/doc-good.texi @@ -230,6 +230,7 @@ If you're bored enough to read this, go see a video of boxed cats @b{Arguments:} the members of @code{Object} + @b{Example:} @example -> in diff --git a/tests/qapi-schema/test-qapi.py b/tests/qapi-schema/test-qapi.py index c7724d3437..fe0ca08d78 100644 --- a/tests/qapi-schema/test-qapi.py +++ b/tests/qapi-schema/test-qapi.py @@ -61,8 +61,8 @@ for doc in schema.docs: print 'doc symbol=%s' % doc.symbol else: print 'doc freeform' - print ' body=\n%s' % doc.body + print ' body=\n%s' % doc.body.text for arg, section in doc.args.iteritems(): - print ' arg=%s\n%s' % (arg, section) + print ' arg=%s\n%s' % (arg, section.text) for section in doc.sections: - print ' section=%s\n%s' % (section.name, section) + print ' section=%s\n%s' % (section.name, section.text) From 76eb6b60edbb15fd2f3beda7da3991951a3b8883 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Mon, 2 Oct 2017 16:13:39 +0200 Subject: [PATCH 09/13] qapi2texi: Simplify representation of section text MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Use a string instead of a list of strings. While there, generate fewer superfluous blank lines. Signed-off-by: Markus Armbruster Message-Id: <20171002141341.24616-10-armbru@redhat.com> Reviewed-by: Marc-André Lureau --- scripts/qapi2texi.py | 33 ++++++++++++++++----------------- tests/qapi-schema/doc-good.texi | 10 ---------- 2 files changed, 16 insertions(+), 27 deletions(-) diff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py index 379d27643d..58add26c11 100755 --- a/scripts/qapi2texi.py +++ b/scripts/qapi2texi.py @@ -13,7 +13,6 @@ MSG_FMT = """ @deftypefn {type} {{}} {name} {body} - @end deftypefn """.format @@ -22,7 +21,6 @@ TYPE_FMT = """ @deftp {{{type}}} {name} {body} - @end deftp """.format @@ -74,7 +72,7 @@ def texi_format(doc): - 1. or 1): generates an @enumerate @item - */-: generates an @itemize list """ - lines = [] + ret = '' doc = subst_braces(doc) doc = subst_vars(doc) doc = subst_emph(doc) @@ -100,32 +98,32 @@ def texi_format(doc): line = '@subsection ' + line[3:] elif re.match(r'^([0-9]*\.) ', line): if not inlist: - lines.append('@enumerate') + ret += '@enumerate\n' inlist = 'enumerate' + ret += '@item\n' line = line[line.find(' ')+1:] - lines.append('@item') elif re.match(r'^[*-] ', line): if not inlist: - lines.append('@itemize %s' % {'*': '@bullet', - '-': '@minus'}[line[0]]) + ret += '@itemize %s\n' % {'*': '@bullet', + '-': '@minus'}[line[0]] inlist = 'itemize' - lines.append('@item') + ret += '@item\n' line = line[2:] elif lastempty and inlist: - lines.append('@end %s\n' % inlist) + ret += '@end %s\n\n' % inlist inlist = '' lastempty = empty - lines.append(line) + ret += line + '\n' if inlist: - lines.append('@end %s\n' % inlist) - return '\n'.join(lines) + ret += '@end %s\n\n' % inlist + return ret def texi_body(doc): """Format the main documentation body""" - return texi_format(doc.body.text) + '\n' + return texi_format(doc.body.text) def texi_enum_value(value): @@ -154,10 +152,11 @@ def texi_members(doc, what, base, variants, member_func): elif (variants and variants.tag_member == section.member and not section.member.type.doc_type()): values = section.member.type.member_names() - desc = 'One of ' + ', '.join(['@t{"%s"}' % v for v in values]) + members_text = ', '.join(['@t{"%s"}' % v for v in values]) + desc = 'One of ' + members_text + '\n' else: - desc = 'Not documented' - items += member_func(section.member) + desc + '\n' + desc = 'Not documented\n' + items += member_func(section.member) + desc if base: items += '@item The members of @code{%s}\n' % base.doc_type() if variants: @@ -182,7 +181,7 @@ def texi_sections(doc): for section in doc.sections: if section.name: # prefer @b over @strong, so txt doesn't translate it to *Foo:* - body += '\n\n@b{%s:}\n' % section.name + body += '\n@b{%s:}\n' % section.name if section.name and section.name.startswith('Example'): body += texi_example(section.text) else: diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.texi index c032f23fc1..1778312581 100644 --- a/tests/qapi-schema/doc-good.texi +++ b/tests/qapi-schema/doc-good.texi @@ -101,7 +101,6 @@ Not documented the first member @end table - @end deftp @@ -118,7 +117,6 @@ Another paragraph (but no @code{var}: line) Not documented @end table - @end deftp @@ -127,7 +125,6 @@ Not documented - @end deftp @@ -143,7 +140,6 @@ Not documented @item The members of @code{Variant2} when @code{base1} is @t{"two"} @end table - @end deftp @@ -160,7 +156,6 @@ One of @t{"one"}, @t{"two"} @item @code{data: Variant2} when @code{type} is @t{"two"} @end table - @end deftp @@ -182,7 +177,6 @@ argument Not documented @end table - @b{Note:} @code{arg3} is undocumented @@ -209,14 +203,12 @@ Duis aute irure dolor <- out @end example - @b{Examples:} @example - *verbatim* - @{braces@} @end example - @b{Since:} 2.10 @@ -230,7 +222,6 @@ If you're bored enough to read this, go see a video of boxed cats @b{Arguments:} the members of @code{Object} - @b{Example:} @example -> in @@ -238,7 +229,6 @@ If you're bored enough to read this, go see a video of boxed cats <- out @end example - @end deftypefn From 8cbf1a537a61b2a1832948f20582839cebdb69de Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Mon, 2 Oct 2017 16:13:40 +0200 Subject: [PATCH 10/13] qapi: Rename QAPIDoc.parser, .section to ._parser, ._section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Markus Armbruster Message-Id: <20171002141341.24616-11-armbru@redhat.com> Reviewed-by: Marc-André Lureau --- scripts/qapi.py | 52 ++++++++++++++++++++++++------------------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/scripts/qapi.py b/scripts/qapi.py index e338868a52..43a54bf40f 100644 --- a/scripts/qapi.py +++ b/scripts/qapi.py @@ -120,11 +120,11 @@ class QAPIDoc(object): self.member = member def __init__(self, parser, info): - # self.parser is used to report errors with QAPIParseError. The + # self._parser is used to report errors with QAPIParseError. The # resulting error position depends on the state of the parser. # It happens to be the beginning of the comment. More or less # servicable, but action at a distance. - self.parser = parser + self._parser = parser self.info = info self.symbol = None self.body = QAPIDoc.Section() @@ -133,7 +133,7 @@ class QAPIDoc(object): # a list of Section self.sections = [] # the current section - self.section = self.body + self._section = self.body def has_section(self, name): """Return True if we have a section with this name.""" @@ -150,7 +150,7 @@ class QAPIDoc(object): return if line[0] != ' ': - raise QAPIParseError(self.parser, "Missing space after #") + raise QAPIParseError(self._parser, "Missing space after #") line = line[1:] # FIXME not nice: things like '# @foo:' and '# @foo: ' aren't @@ -159,11 +159,11 @@ class QAPIDoc(object): self._append_symbol_line(line) elif not self.body.text and line.startswith('@'): if not line.endswith(':'): - raise QAPIParseError(self.parser, "Line should end with :") + raise QAPIParseError(self._parser, "Line should end with :") self.symbol = line[1:-1] # FIXME invalid names other than the empty string aren't flagged if not self.symbol: - raise QAPIParseError(self.parser, "Invalid name") + raise QAPIParseError(self._parser, "Invalid name") else: self._append_freeform(line) @@ -189,48 +189,48 @@ class QAPIDoc(object): def _start_args_section(self, name): # FIXME invalid names other than the empty string aren't flagged if not name: - raise QAPIParseError(self.parser, "Invalid parameter name") + raise QAPIParseError(self._parser, "Invalid parameter name") if name in self.args: - raise QAPIParseError(self.parser, + raise QAPIParseError(self._parser, "'%s' parameter name duplicated" % name) if self.sections: - raise QAPIParseError(self.parser, + raise QAPIParseError(self._parser, "'@%s:' can't follow '%s' section" % (name, self.sections[0].name)) self._end_section() - self.section = QAPIDoc.ArgSection(name) - self.args[name] = self.section + self._section = QAPIDoc.ArgSection(name) + self.args[name] = self._section def _start_section(self, name=None): if name in ('Returns', 'Since') and self.has_section(name): - raise QAPIParseError(self.parser, + raise QAPIParseError(self._parser, "Duplicated '%s' section" % name) self._end_section() - self.section = QAPIDoc.Section(name) - self.sections.append(self.section) + self._section = QAPIDoc.Section(name) + self.sections.append(self._section) def _end_section(self): - if self.section: - text = self.section.text = self.section.text.strip() - if self.section.name and (not text or text.isspace()): - raise QAPIParseError(self.parser, "Empty doc section '%s'" - % self.section.name) - self.section = None + if self._section: + text = self._section.text = self._section.text.strip() + if self._section.name and (not text or text.isspace()): + raise QAPIParseError(self._parser, "Empty doc section '%s'" + % self._section.name) + self._section = None def _append_freeform(self, line): - in_arg = isinstance(self.section, QAPIDoc.ArgSection) - if (in_arg and self.section.text.endswith('\n\n') + in_arg = isinstance(self._section, QAPIDoc.ArgSection) + if (in_arg and self._section.text.endswith('\n\n') and line and not line[0].isspace()): self._start_section() - if (in_arg or not self.section.name - or not self.section.name.startswith('Example')): + if (in_arg or not self._section.name + or not self._section.name.startswith('Example')): line = line.strip() match = re.match(r'(@\S+:)', line) if match: - raise QAPIParseError(self.parser, + raise QAPIParseError(self._parser, "'%s' not allowed in free-form documentation" % match.group(1)) - self.section.append(line) + self._section.append(line) def connect_member(self, member): if member.name not in self.args: From 7e21572ce768a1b4cd4d4b24405d5f75448bbf62 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Mon, 2 Oct 2017 16:13:41 +0200 Subject: [PATCH 11/13] qapi2texi: De-duplicate code to add blank line before symbol MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Markus Armbruster Message-Id: <20171002141341.24616-12-armbru@redhat.com> Reviewed-by: Marc-André Lureau --- scripts/qapi2texi.py | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py index 58add26c11..92e2af2cd6 100755 --- a/scripts/qapi2texi.py +++ b/scripts/qapi2texi.py @@ -206,8 +206,6 @@ class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor): def visit_enum_type(self, name, info, values, prefix): doc = self.cur_doc - if self.out: - self.out += '\n' self.out += TYPE_FMT(type='Enum', name=doc.symbol, body=texi_entity(doc, 'Values', @@ -217,16 +215,12 @@ class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor): doc = self.cur_doc if base and base.is_implicit(): base = None - if self.out: - self.out += '\n' self.out += TYPE_FMT(type='Object', name=doc.symbol, body=texi_entity(doc, 'Members', base, variants)) def visit_alternate_type(self, name, info, variants): doc = self.cur_doc - if self.out: - self.out += '\n' self.out += TYPE_FMT(type='Alternate', name=doc.symbol, body=texi_entity(doc, 'Members')) @@ -234,8 +228,6 @@ class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor): def visit_command(self, name, info, arg_type, ret_type, gen, success_response, boxed): doc = self.cur_doc - if self.out: - self.out += '\n' if boxed: body = texi_body(doc) body += ('\n@b{Arguments:} the members of @code{%s}\n' @@ -249,13 +241,13 @@ class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor): def visit_event(self, name, info, arg_type, boxed): doc = self.cur_doc - if self.out: - self.out += '\n' self.out += MSG_FMT(type='Event', name=doc.symbol, body=texi_entity(doc, 'Arguments')) def symbol(self, doc, entity): + if self.out: + self.out += '\n' self.cur_doc = doc entity.visit(self) self.cur_doc = None From 0b263ecbcf71273abc8f79762e2349841a003c27 Mon Sep 17 00:00:00 2001 From: Chen Hanxiao Date: Thu, 12 Oct 2017 14:44:48 +0800 Subject: [PATCH 12/13] qapi-docs: fix a comment typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit s/Subection/Subsection Signed-off-by: Chen Hanxiao Message-Id: <20171012064448.20276-1-chen_han_xiao@126.com> Reviewed-by: Marc-André Lureau Signed-off-by: Markus Armbruster --- docs/devel/qapi-code-gen.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index f04c63fe82..06ab699066 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.txt @@ -63,7 +63,7 @@ Comment text starting with '=' is a section title: Double the '=' for a subsection title: - # == Subection title + # == Subsection title '|' denotes examples: From 49ccefde303c84d291c70842922c37b6de6ef15a Mon Sep 17 00:00:00 2001 From: Daniel Henrique Barboza Date: Wed, 20 Dec 2017 08:23:04 -0200 Subject: [PATCH 13/13] qmp: remove qmp_cpu 'qmp_cpu' was implemented in commit 755f196898 ("qapi: Convert the cpu command") as a functional no-op, a QMP call that does nothing and return success. The idea, apparently, was to provide a counterpart for the HMP 'hmp_cpu' command, introduced in the same commit. After 6 years of its creation, qmp_cpu remains a functional no-op that does nothing, having no value for any caller/user. A proposal was sent to implement qmp_cpu like hmp_cpu works, but it was denied [1]. The reason is that QMP must be as stateless as possible and a function that changes its state (the current CPU monitor in the case of qmp_cpu) goes against it. Any QMP command that needs a specific monitor CPU setup must provide it in its arguments, instead of relying in the current QMP monitor state. After discussions that happened in [2] it was decided that a command that does nothing since its birth, no one uses for anything and will not be implemented, should be deprecated and erased. Given that we will *not* provide any replacement for qmp_cpu and we believe that there is no user relying on it, there is no point in adding a deprecation delay for it. So, this patch nukes qmp_cpu from QEMU code, removing both its blank implementation in qmp.c and its doc in qapi-schema.json. [1] https://lists.gnu.org/archive/html/qemu-devel/2017-12/msg02283.html [2] https://lists.gnu.org/archive/html/qemu-devel/2017-12/msg03696.html Signed-off-by: Daniel Henrique Barboza CC: Markus Armbruster CC: Eric Blake CC: Daniel P. Berrange Message-Id: <20171220102304.8288-1-danielhb@linux.vnet.ibm.com> Reviewed-by: Daniel P. Berrange Signed-off-by: Markus Armbruster --- qapi-schema.json | 11 ----------- qmp.c | 5 ----- 2 files changed, 16 deletions(-) diff --git a/qapi-schema.json b/qapi-schema.json index ea3723f903..5c06745c79 100644 --- a/qapi-schema.json +++ b/qapi-schema.json @@ -1045,17 +1045,6 @@ ## { 'command': 'system_powerdown' } -## -# @cpu: -# -# This command is a nop that is only provided for the purposes of compatibility. -# -# Since: 0.14.0 -# -# Notes: Do not use this command. -## -{ 'command': 'cpu', 'data': {'index': 'int'} } - ## # @cpu-add: # diff --git a/qmp.c b/qmp.c index e8c303116a..52cfd2d81c 100644 --- a/qmp.c +++ b/qmp.c @@ -113,11 +113,6 @@ void qmp_system_powerdown(Error **erp) qemu_system_powerdown_request(); } -void qmp_cpu(int64_t index, Error **errp) -{ - /* Just do nothing */ -} - void qmp_cpu_add(int64_t id, Error **errp) { MachineClass *mc;