[Qemu-devel] [PATCH 00/11] qapi: Cleanups around qapi2texi

[Qemu-devel] [PATCH 00/11] qapi: Cleanups around qapi2texi

[Markus Armbruster]

Markus Armbruster (11):
  qapi-schema: Fix query-vm-generation-id's doc comment markup
  qapi: Stop rejecting #optional
  qapi: Eliminate QAPISchemaParser.__init__()'s local fname
  qapi: Make cur_doc local to QAPISchemaParser.__init__()
  tests/qapi-schema/doc-bad-section: New, factored out of doc-good
  qapi2texi: Clean up texi_sections()
  qapi: Unify representation of doc section without name
  qapi: Simplify representation of QAPIDoc section text
  qapi2texi: Simplify representation of section text
  qapi: Rename QAPIDoc.parser, .section to ._parser, ._section
  qapi2texi: De-duplicate code to add blank line before symbol

 qapi-schema.json                       |   2 +-
 scripts/qapi.py                        | 107 +++++++++++++++------------------
 scripts/qapi2texi.py                   |  65 +++++++++-----------
 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         |   4 +-
 tests/qapi-schema/doc-good.texi        |  11 +---
 tests/qapi-schema/test-qapi.py         |   6 +-
 12 files changed, 110 insertions(+), 114 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

-- 
2.13.6

[Qemu-devel] [PATCH 01/11] qapi-schema: Fix query-vm-generation-id's doc comment markup

[Markus Armbruster]

Reported-by: Daniel P. Berrange <berrange@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi-schema.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/qapi-schema.json b/qapi-schema.json
index a9dd043f65..3490a5edaf 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' }
 
-- 
2.13.6

[Qemu-devel] [PATCH 02/11] qapi: Stop rejecting #optional

[Markus Armbruster]

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 <armbru@redhat.com>
---
 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):
-- 
2.13.6

[Qemu-devel] [PATCH 03/11] qapi: Eliminate QAPISchemaParser.__init__()'s local fname

[Markus Armbruster]

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 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()
-- 
2.13.6

[Qemu-devel] [PATCH 04/11] qapi: Make cur_doc local to QAPISchemaParser.__init__()

[Markus Armbruster]

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 <armbru@redhat.com>
---
 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)
-- 
2.13.6

[Qemu-devel] [PATCH 05/11] tests/qapi-schema/doc-bad-section: New, factored out of doc-good

[Markus Armbruster]

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 <armbru@redhat.com>
---
 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 abc6707ef2..de4a713c25 100644
--- a/tests/Makefile.include
+++ b/tests/Makefile.include
@@ -412,6 +412,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
@@ -429,10 +430,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
-- 
2.13.6

[Qemu-devel] [PATCH 06/11] qapi2texi: Clean up texi_sections()

[Markus Armbruster]

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 <armbru@redhat.com>
---
 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
 
 
-- 
2.13.6

[Qemu-devel] [PATCH 07/11] qapi: Unify representation of doc section without name

[Markus Armbruster]

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 <armbru@redhat.com>
---
 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=
-- 
2.13.6

[Qemu-devel] [PATCH 08/11] qapi: Simplify representation of QAPIDoc section text

[Markus Armbruster]

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 <armbru@redhat.com>
---
 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)
-- 
2.13.6

[Qemu-devel] [PATCH 09/11] qapi2texi: Simplify representation of section text

[Markus Armbruster]

Use a string instead of a list of strings.  While there, generate
fewer superfluous blank lines.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 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
 
 
-- 
2.13.6

[Qemu-devel] [PATCH 10/11] qapi: Rename QAPIDoc.parser, .section to ._parser, ._section

[Markus Armbruster]

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 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:
-- 
2.13.6

[Qemu-devel] [PATCH 11/11] qapi2texi: De-duplicate code to add blank line before symbol

[Markus Armbruster]

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 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
-- 
2.13.6

Re: [Qemu-devel] [PATCH 01/11] qapi-schema: Fix query-vm-generation-id's doc comment markup

[Marc-André Lureau]

On Mon, Oct 2, 2017 at 4:13 PM, Markus Armbruster <armbru@redhat.com> wrote:
> Reported-by: Daniel P. Berrange <berrange@redhat.com>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>

(reviweing this patch makes me realize that the last
expression/command in qapi-schema isn't in the generated doc..)

> ---
>  qapi-schema.json | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/qapi-schema.json b/qapi-schema.json
> index a9dd043f65..3490a5edaf 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' }
>
> --
> 2.13.6
>
>



-- 
Marc-André Lureau

Re: [Qemu-devel] [PATCH 02/11] qapi: Stop rejecting #optional

[Marc-André Lureau]

On Mon, Oct 2, 2017 at 4:13 PM, Markus Armbruster <armbru@redhat.com> wrote:
> 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 <armbru@redhat.com>

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>

> ---
>  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):
> --
> 2.13.6
>
>



-- 
Marc-André Lureau

Re: [Qemu-devel] [PATCH 03/11] qapi: Eliminate QAPISchemaParser.__init__()'s local fname

[Marc-André Lureau]

On Mon, Oct 2, 2017 at 4:13 PM, Markus Armbruster <armbru@redhat.com> wrote:
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>


> ---
>  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()
> --
> 2.13.6
>
>



-- 
Marc-André Lureau

Re: [Qemu-devel] [PATCH 04/11] qapi: Make cur_doc local to QAPISchemaParser.__init__()

[Marc-André Lureau]

On Mon, Oct 2, 2017 at 4:13 PM, Markus Armbruster <armbru@redhat.com> wrote:
> 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 <armbru@redhat.com>

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>


> ---
>  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)
> --
> 2.13.6
>
>



-- 
Marc-André Lureau

Re: [Qemu-devel] [PATCH 05/11] tests/qapi-schema/doc-bad-section: New, factored out of doc-good

[Marc-André Lureau]

On Mon, Oct 2, 2017 at 4:13 PM, Markus Armbruster <armbru@redhat.com> wrote:
> 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 <armbru@redhat.com>

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>


> ---
>  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 abc6707ef2..de4a713c25 100644
> --- a/tests/Makefile.include
> +++ b/tests/Makefile.include
> @@ -412,6 +412,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
> @@ -429,10 +430,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
> --
> 2.13.6
>
>



-- 
Marc-André Lureau

Re: [Qemu-devel] [PATCH 06/11] qapi2texi: Clean up texi_sections()

[Marc-André Lureau]

On Mon, Oct 2, 2017 at 4:13 PM, Markus Armbruster <armbru@redhat.com> wrote:
> 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 <armbru@redhat.com>

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>


> ---
>  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
>
>
> --
> 2.13.6
>
>



-- 
Marc-André Lureau

Re: [Qemu-devel] [PATCH 07/11] qapi: Unify representation of doc section without name

[Marc-André Lureau]

On Mon, Oct 2, 2017 at 4:13 PM, Markus Armbruster <armbru@redhat.com> wrote:
> 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 <armbru@redhat.com>

> ---
>  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=
> --
> 2.13.6
>
>



-- 
Marc-André Lureau

Re: [Qemu-devel] [PATCH 07/11] qapi: Unify representation of doc section without name

[Marc-André Lureau]

On Mon, Oct 2, 2017 at 4:13 PM, Markus Armbruster <armbru@redhat.com> wrote:
> 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 <armbru@redhat.com>

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>


> ---
>  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=
> --
> 2.13.6
>
>



-- 
Marc-André Lureau

Re: [Qemu-devel] [PATCH 09/11] qapi2texi: Simplify representation of section text

[Marc-André Lureau]

On Mon, Oct 2, 2017 at 4:13 PM, Markus Armbruster <armbru@redhat.com> wrote:
> Use a string instead of a list of strings.  While there, generate
> fewer superfluous blank lines.
>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>


> ---
>  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
>
>
> --
> 2.13.6
>
>



-- 
Marc-André Lureau

Re: [Qemu-devel] [PATCH 08/11] qapi: Simplify representation of QAPIDoc section text

[Marc-André Lureau]

On Mon, Oct 2, 2017 at 4:13 PM, Markus Armbruster <armbru@redhat.com> wrote:
> 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 <armbru@redhat.com>

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>


> ---
>  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)
> --
> 2.13.6
>
>



-- 
Marc-André Lureau

Re: [Qemu-devel] [PATCH 10/11] qapi: Rename QAPIDoc.parser, .section to ._parser, ._section

[Marc-André Lureau]

On Mon, Oct 2, 2017 at 4:13 PM, Markus Armbruster <armbru@redhat.com> wrote:
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>


> ---
>  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:
> --
> 2.13.6
>
>



-- 
Marc-André Lureau

Re: [Qemu-devel] [PATCH 11/11] qapi2texi: De-duplicate code to add blank line before symbol

[Marc-André Lureau]

On Mon, Oct 2, 2017 at 4:13 PM, Markus Armbruster <armbru@redhat.com> wrote:
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>


> ---
>  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
> --
> 2.13.6
>
>



-- 
Marc-André Lureau

Re: [Qemu-devel] [PATCH 01/11] qapi-schema: Fix query-vm-generation-id's doc comment markup

[Markus Armbruster]

Marc-André Lureau <marcandre.lureau@gmail.com> writes:

> On Mon, Oct 2, 2017 at 4:13 PM, Markus Armbruster <armbru@redhat.com> wrote:
>> Reported-by: Daniel P. Berrange <berrange@redhat.com>
>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>
> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>

Thanks!

> (reviweing this patch makes me realize that the last
> expression/command in qapi-schema isn't in the generated doc..)

Oh.  We better fix that.

Re: [Qemu-devel] [PATCH 01/11] qapi-schema: Fix query-vm-generation-id's doc comment markup

[Marc-André Lureau]

Hi

On Wed, Oct 4, 2017 at 3:03 PM, Markus Armbruster <armbru@redhat.com> wrote:
> Marc-André Lureau <marcandre.lureau@gmail.com> writes:
>
>> On Mon, Oct 2, 2017 at 4:13 PM, Markus Armbruster <armbru@redhat.com> wrote:
>>> Reported-by: Daniel P. Berrange <berrange@redhat.com>
>>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>>
>> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
>
> Thanks!
>
>> (reviweing this patch makes me realize that the last
>> expression/command in qapi-schema isn't in the generated doc..)
>
> Oh.  We better fix that.

Ah no, it's because I had an old docs/qemu-qmp-qapi.texi in my build tree...



-- 
Marc-André Lureau