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>

13 files changed, 78 insertions, 89 deletions

diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
index f3e7ced212..9eede44350 100644
--- a/docs/devel/qapi-code-gen.txt
+++ b/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
diff --git a/qapi/audio.json b/qapi/audio.json
index f62bd0d7f6..3b843878d2 100644
--- a/qapi/audio.json
+++ b/qapi/audio.json
@@ -159,20 +159,20 @@
 # recording.
 #
 # @server-name: select from among several possible concurrent server instances
-# (default: environment variable $JACK_DEFAULT_SERVER if set, else "default")
+#               (default: environment variable $JACK_DEFAULT_SERVER if set, else "default")
 #
 # @client-name: the client name to use. The server will modify this name to
-# create a unique variant, if needed unless @exact-name is true (default: the
-# guest's name)
+#               create a unique variant, if needed unless @exact-name is true (default: the
+#               guest's name)
 #
 # @connect-ports: if set, a regular expression of JACK client port name(s) to
-# monitor for and automatically connect to
+#                 monitor for and automatically connect to
 #
 # @start-server: start a jack server process if one is not already present
-# (default: false)
+#                (default: false)
 #
 # @exact-name: use the exact name requested otherwise JACK automatically
-# generates a unique one, if needed (default: false)
+#              generates a unique one, if needed (default: false)
 #
 # Since: 5.1
 ##
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 55b58ba892..c5ac22d246 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -373,7 +373,7 @@
 #
 # Features:
 # @deprecated: Member @encryption_key_missing is deprecated.  It is
-#     always false.
+#              always false.
 #
 # Since: 0.14.0
 #
@@ -508,7 +508,7 @@
 #
 # Features:
 # @deprecated: Member @status is deprecated.  Use @recording and
-#     @locked instead.
+#              @locked instead.
 #
 # Since: 1.3
 ##
@@ -618,7 +618,7 @@
 #
 # Features:
 # @deprecated: Member @dirty-bitmaps is deprecated.  Use @inserted
-#     member @dirty-bitmaps instead.
+#              member @dirty-bitmaps instead.
 #
 # Since:  0.14.0
 ##
@@ -1646,7 +1646,7 @@
 #
 # Features:
 # @deprecated: Members @base and @top are deprecated.  Use @base-node
-#     and @top-node instead.
+#              and @top-node instead.
 #
 # Returns: - Nothing on success
 #          - If @device does not exist, DeviceNotFound
@@ -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',
diff --git a/qapi/control.json b/qapi/control.json
index de51e9916c..134f842baf 100644
--- a/qapi/control.json
+++ b/qapi/control.json
@@ -177,8 +177,8 @@
 #
 # Features:
 # @deprecated: This command is deprecated, because its output doesn't
-#     reflect compile-time configuration.  Use 'query-qmp-schema'
-#     instead.
+#              reflect compile-time configuration.  Use 'query-qmp-schema'
+#              instead.
 #
 # Returns: A list of @EventInfo.
 #
diff --git a/qapi/machine.json b/qapi/machine.json
index abc6fd0477..0ac1880e4a 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -191,8 +191,8 @@
 #
 # Features:
 # @deprecated: This command is deprecated, because it interferes with
-#     the guest.  Use 'query-cpus-fast' instead to avoid the vCPU
-#     interruption.
+#              the guest.  Use 'query-cpus-fast' instead to avoid the vCPU
+#              interruption.
 #
 # Returns: a list of @CpuInfo for each virtual CPU
 #
@@ -316,7 +316,7 @@
 #
 # Features:
 # @deprecated: This command is deprecated.  Use `device_add` instead.
-#     See the `query-hotpluggable-cpus` command for details.
+#              See the `query-hotpluggable-cpus` command for details.
 #
 # Returns: Nothing on success
 #
diff --git a/qapi/migration.json b/qapi/migration.json
index 5f6b06172c..675f70bb67 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -667,18 +667,18 @@
 #                       Defaults to none. (Since 5.0)
 #
 # @multifd-zlib-level: Set the compression level to be used in live
-#          migration, the compression level is an integer between 0
-#          and 9, where 0 means no compression, 1 means the best
-#          compression speed, and 9 means best compression ratio which
-#          will consume more CPU.
-#          Defaults to 1. (Since 5.0)
+#                      migration, the compression level is an integer between 0
+#                      and 9, where 0 means no compression, 1 means the best
+#                      compression speed, and 9 means best compression ratio which
+#                      will consume more CPU.
+#                      Defaults to 1. (Since 5.0)
 #
 # @multifd-zstd-level: Set the compression level to be used in live
-#          migration, the compression level is an integer between 0
-#          and 20, where 0 means no compression, 1 means the best
-#          compression speed, and 20 means best compression ratio which
-#          will consume more CPU.
-#          Defaults to 1. (Since 5.0)
+#                      migration, the compression level is an integer between 0
+#                      and 20, where 0 means no compression, 1 means the best
+#                      compression speed, and 20 means best compression ratio which
+#                      will consume more CPU.
+#                      Defaults to 1. (Since 5.0)
 #
 # @block-bitmap-mapping: Maps block nodes and bitmaps on them to
 #          aliases for the purpose of dirty bitmap migration.  Such
@@ -827,18 +827,18 @@
 #                       Defaults to none. (Since 5.0)
 #
 # @multifd-zlib-level: Set the compression level to be used in live
-#          migration, the compression level is an integer between 0
-#          and 9, where 0 means no compression, 1 means the best
-#          compression speed, and 9 means best compression ratio which
-#          will consume more CPU.
-#          Defaults to 1. (Since 5.0)
+#                      migration, the compression level is an integer between 0
+#                      and 9, where 0 means no compression, 1 means the best
+#                      compression speed, and 9 means best compression ratio which
+#                      will consume more CPU.
+#                      Defaults to 1. (Since 5.0)
 #
 # @multifd-zstd-level: Set the compression level to be used in live
-#          migration, the compression level is an integer between 0
-#          and 20, where 0 means no compression, 1 means the best
-#          compression speed, and 20 means best compression ratio which
-#          will consume more CPU.
-#          Defaults to 1. (Since 5.0)
+#                      migration, the compression level is an integer between 0
+#                      and 20, where 0 means no compression, 1 means the best
+#                      compression speed, and 20 means best compression ratio which
+#                      will consume more CPU.
+#                      Defaults to 1. (Since 5.0)
 #
 # @block-bitmap-mapping: Maps block nodes and bitmaps on them to
 #          aliases for the purpose of dirty bitmap migration.  Such
@@ -1023,18 +1023,18 @@
 #                       Defaults to none. (Since 5.0)
 #
 # @multifd-zlib-level: Set the compression level to be used in live
-#          migration, the compression level is an integer between 0
-#          and 9, where 0 means no compression, 1 means the best
-#          compression speed, and 9 means best compression ratio which
-#          will consume more CPU.
-#          Defaults to 1. (Since 5.0)
+#                      migration, the compression level is an integer between 0
+#                      and 9, where 0 means no compression, 1 means the best
+#                      compression speed, and 9 means best compression ratio which
+#                      will consume more CPU.
+#                      Defaults to 1. (Since 5.0)
 #
 # @multifd-zstd-level: Set the compression level to be used in live
-#          migration, the compression level is an integer between 0
-#          and 20, where 0 means no compression, 1 means the best
-#          compression speed, and 20 means best compression ratio which
-#          will consume more CPU.
-#          Defaults to 1. (Since 5.0)
+#                      migration, the compression level is an integer between 0
+#                      and 20, where 0 means no compression, 1 means the best
+#                      compression speed, and 20 means best compression ratio which
+#                      will consume more CPU.
+#                      Defaults to 1. (Since 5.0)
 #
 # @block-bitmap-mapping: Maps block nodes and bitmaps on them to
 #          aliases for the purpose of dirty bitmap migration.  Such
@@ -1362,7 +1362,7 @@
 #
 # Features:
 # @deprecated: This command is deprecated.  Use
-#     'migrate-set-parameters' instead.
+#              'migrate-set-parameters' instead.
 #
 # Returns: nothing on success
 #
@@ -1386,7 +1386,7 @@
 #
 # Features:
 # @deprecated: This command is deprecated.  Use
-#     'migrate-set-parameters' instead.
+#              'migrate-set-parameters' instead.
 #
 # Returns: nothing on success
 #
@@ -1410,7 +1410,7 @@
 #
 # Features:
 # @deprecated: This command is deprecated.  Use
-#     'migrate-set-parameters' instead.
+#              'migrate-set-parameters' instead.
 #
 # The size will be rounded down to the nearest power of 2.
 # The cache size can be modified before and during ongoing migration
@@ -1436,7 +1436,7 @@
 #
 # Features:
 # @deprecated: This command is deprecated.  Use
-#     'query-migrate-parameters' instead.
+#              'query-migrate-parameters' instead.
 #
 # Returns: XBZRLE cache size in bytes
 #
diff --git a/qapi/misc.json b/qapi/misc.json
index 9d32820dc1..8cf6ebe67c 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -877,8 +877,8 @@
 #
 # Features:
 # @deprecated: This command is deprecated.  For changing block
-#     devices, use 'blockdev-change-medium' instead; for changing VNC
-#     parameters, use 'change-vnc-password' instead.
+#              devices, use 'blockdev-change-medium' instead; for changing VNC
+#              parameters, use 'change-vnc-password' instead.
 #
 # Returns: - Nothing on success.
 #          - If @device is not a valid block device, DeviceNotFound
diff --git a/qapi/net.json b/qapi/net.json
index ddb113e5e5..a3a1336001 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -457,7 +457,7 @@
 #
 # Since: 2.7
 #
-# @vhost-vdpa since 5.1
+#        @vhost-vdpa since 5.1
 ##
 { 'enum': 'NetClientDriver',
   'data': [ 'none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'vde',
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index abadacbb0e..165925ca72 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -52,8 +52,8 @@ class QAPISchemaParser:
             info = self.info
             if self.tok == '#':
                 self.reject_expr_doc(cur_doc)
-                cur_doc = self.get_doc(info)
-                self.docs.append(cur_doc)
+                for cur_doc in self.get_doc(info):
+                    self.docs.append(cur_doc)
                 continue
 
             expr = self.get_expr(False)
@@ -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):
diff --git a/tests/qapi-schema/doc-bad-section.err b/tests/qapi-schema/doc-bad-section.err
index e69de29bb2..785cacc08c 100644
--- a/tests/qapi-schema/doc-bad-section.err
+++ b/tests/qapi-schema/doc-bad-section.err
@@ -0,0 +1 @@
+doc-bad-section.json:5:1: unexpected '=' markup in definition documentation
diff --git a/tests/qapi-schema/doc-bad-section.json b/tests/qapi-schema/doc-bad-section.json
index 560df4b087..8175d95867 100644
--- a/tests/qapi-schema/doc-bad-section.json
+++ b/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
diff --git a/tests/qapi-schema/doc-bad-section.out b/tests/qapi-schema/doc-bad-section.out
index 367e2a1c3e..e69de29bb2 100644
--- a/tests/qapi-schema/doc-bad-section.out
+++ b/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
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index 6757dd26a2..d78a424cd9 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/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_