QAPI patches patches for 2020-09-08

-----BEGIN PGP SIGNATURE-----
 
 iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAl9XH3wSHGFybWJydUBy
 ZWRoYXQuY29tAAoJEDhwtADrkYZT2GwP/3nJIqiVF4QLp2RdZkCqiuIc4pSCJLjc
 4x75sOIsuAhNpiARvjEtsP+mlNeK+FND7Naem9ERHYVqrz8r+3jJf1EVw/sZhkg8
 f0mOism4bHji8SmpZihYiB/clgDgMpw2wc+Q6zwgSzzj81FR3HANC0gsaTXBAs8F
 B7oZ0ytpcfQNvWoXLvYSpr/5cm8mtnsLbbXoj70RfLpCqTdB1Tl8fYEfVFT8XDUd
 jIZr2UmsTTUnNI9CrIAgVTe14awRMSUnM2f8HKNWm7MFUeV3x/I1G6p2IE8Fvg+X
 k0LZkD3YSBSP2cMupwdHZ0/1WuoHV+gFOoDgPfy/wW70rpmoXpttwhJdWMya/CRt
 Ovcnj5MNUiPIlIY7qHa5E7M8Bc+ctfkXI6zsvsyzewEZxJn2YYO6wKZj6Ac4/Ztf
 7ggccRk5doc/GNXRWdPSF1dQnIvZm6vHk0AcPvHZmHM/AgwG+1g8j0aoOxLnluBf
 HFfo2+0qosYg9yTCHnWuoY9SS/NCpt7SbdqBytLYgcCXPTNMdNax492nZoO8qlcA
 dFRl7OBg9ANxiA/0GhJg3J8SwMwKEURMArkvxJhFY+MQ5AMPhjyMYxyawCA4Hq4W
 mMQgyjXk7EBZjz3dvgiAM8f4c66YfpLATObAKdk035z3ci/oih8guLnZBjtC/oNo
 LgwmoSPg+lc2
 =59S5
 -----END PGP SIGNATURE-----

Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2020-09-08' into staging

QAPI patches patches for 2020-09-08

# gpg: Signature made Tue 08 Sep 2020 07:06:52 BST
# gpg:                using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653
# gpg:                issuer "armbru@redhat.com"
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [full]
# gpg:                 aka "Markus Armbruster <armbru@pond.sub.org>" [full]
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867  4E5F 3870 B400 EB91 8653

* remotes/armbru/tags/pull-qapi-2020-09-08:
  qapi/block-core.json: Fix nbd-server-start docs
  qapi: Fix indentation, again
  qapi/migration.json: Fix indentation
  qapi: Make section headings start a new doc comment block
  qapi: Reject section markup in definition documentation

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

docs/devel/qapi-code-gen.txt

@@ -835,6 +835,8 @@ Double the '=' for a subsection title:
 
     # == Subsection title
 
+Both are only permitted in free-form documentation.
+
 '|' denotes examples:
 
     # | Text of the example, may span

qapi/block-core.json

@@ -5211,6 +5211,9 @@
 # server will present them as named exports; for example, another
 # QEMU instance could refer to them as "nbd:HOST:PORT:exportname=NAME".
 #
+# Keep this type consistent with the NbdServerOptions type. The only intended
+# difference is using SocketAddressLegacy instead of SocketAddress.
+#
 # @addr: Address on which to listen.
 # @tls-creds: ID of the TLS credentials object (since 2.6).
 # @tls-authz: ID of the QAuthZ authorization object used to validate
@@ -5221,9 +5224,6 @@
 #
 # Returns: error if the server is already running.
 #
-# Keep this type consistent with the NbdServerOptions type. The only intended
-# difference is using SocketAddressLegacy instead of SocketAddress.
-#
 # Since: 1.3.0
 ##
 { 'command': 'nbd-server-start',

scripts/qapi/parser.py

@@ -52,7 +52,7 @@ class QAPISchemaParser:
             info = self.info
             if self.tok == '#':
                 self.reject_expr_doc(cur_doc)
-                cur_doc = self.get_doc(info)
+                for cur_doc in self.get_doc(info):
                     self.docs.append(cur_doc)
                 continue
 
@@ -270,7 +270,8 @@ class QAPISchemaParser:
             raise QAPIParseError(
                 self, "junk after '##' at start of documentation comment")
 
-        doc = QAPIDoc(self, info)
+        docs = []
+        cur_doc = QAPIDoc(self, info)
         self.accept(False)
         while self.tok == '#':
             if self.val.startswith('##'):
@@ -279,10 +280,20 @@ class QAPISchemaParser:
                     raise QAPIParseError(
                         self,
                         "junk after '##' at end of documentation comment")
-                doc.end_comment()
+                cur_doc.end_comment()
+                docs.append(cur_doc)
                 self.accept()
-                return doc
-            doc.append(self.val)
+                return docs
+            if self.val.startswith('# ='):
+                if cur_doc.symbol:
+                    raise QAPIParseError(
+                        self,
+                        "unexpected '=' markup in definition documentation")
+                if cur_doc.body.text:
+                    cur_doc.end_comment()
+                    docs.append(cur_doc)
+                    cur_doc = QAPIDoc(self, info)
+            cur_doc.append(self.val)
             self.accept(False)
 
         raise QAPIParseError(self, "documentation comment must end with '##'")
@@ -311,7 +322,6 @@ class QAPIDoc:
         def __init__(self, name=None):
             # optional section name (argument/member or section name)
             self.name = name
-            # the list of lines for this section
             self.text = ''
 
         def append(self, line):

tests/qapi-schema/doc-bad-section.err

@@ -0,0 +1 @@
+doc-bad-section.json:5:1: unexpected '=' markup in definition documentation

tests/qapi-schema/doc-bad-section.json

@@ -1,9 +1,8 @@
 # = section within an expression comment
-# BUG: not rejected
 
 ##
 # @Enum:
-# == Produces *invalid* texinfo
+# == No good here
 # @one: The _one_ {and only}
 #
 # @two is undocumented

tests/qapi-schema/doc-bad-section.out

@@ -1,24 +0,0 @@
-module None
-object q_empty
-enum QType
-    prefix QTYPE
-    member none
-    member qnull
-    member qnum
-    member qstring
-    member qdict
-    member qlist
-    member qbool
-module doc-bad-section.json
-enum Enum
-    member one
-    member two
-doc symbol=Enum
-    body=
-== Produces *invalid* texinfo
-    arg=one
-The _one_ {and only}
-    arg=two
-
-    section=None
-@two is undocumented

tests/qapi-schema/doc-good.out

@@ -69,7 +69,8 @@ event EVT-BOXED Object
 doc freeform
     body=
 = Section
-
+doc freeform
+    body=
 == Subsection
 
 *strong* _with emphasis_