From d98884b75df3676f94d93fbaf6372ca705dc2aee Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 20 Mar 2020 10:18:04 +0100 Subject: [PATCH 1/5] qapi: Reject section markup in definition documentation Section markup in definition documentation makes no sense and can produce invalid Texinfo. Reject. Signed-off-by: Markus Armbruster Message-Id: <20200320091805.5585-2-armbru@redhat.com> Reviewed-by: Eric Blake --- docs/devel/qapi-code-gen.txt | 2 ++ scripts/qapi/parser.py | 5 +++++ tests/qapi-schema/doc-bad-section.err | 1 + tests/qapi-schema/doc-bad-section.json | 3 +-- tests/qapi-schema/doc-bad-section.out | 24 ------------------------ 5 files changed, 9 insertions(+), 26 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/scripts/qapi/parser.py b/scripts/qapi/parser.py index abadacbb0e..f12c67d7d2 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -282,6 +282,11 @@ class QAPISchemaParser: doc.end_comment() self.accept() return doc + if self.val.startswith('# ='): + if doc.symbol: + raise QAPIParseError( + self, + "unexpected '=' markup in definition documentation") doc.append(self.val) self.accept(False) 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 From dcdc07a97cbe57369d75077c9d3ea035f8c5f483 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 20 Mar 2020 10:18:05 +0100 Subject: [PATCH 2/5] qapi: Make section headings start a new doc comment block Our current QAPI doc-comment markup allows section headers (introduced with a leading '=' or '==') anywhere in a free-form documentation comment. This works for Texinfo because the generator simply prints a Texinfo section command at that point in the output stream. For rST generation, since we're assembling a tree of docutils nodes, this is awkward because a new section implies starting a new section node at the top level of the tree and generating text into there. Make section headers start a new free-form documentation block, so the future rST document generator doesn't have to look at every line in free-form blocks and handle headings in odd places. This change makes no difference to the generated Texinfo. Signed-off-by: Markus Armbruster Message-Id: <20200320091805.5585-3-armbru@redhat.com> --- scripts/qapi/parser.py | 21 +++++++++++++-------- tests/qapi-schema/doc-good.out | 3 ++- 2 files changed, 15 insertions(+), 9 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index f12c67d7d2..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,15 +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 + return docs if self.val.startswith('# ='): - if doc.symbol: + if cur_doc.symbol: raise QAPIParseError( self, "unexpected '=' markup in definition documentation") - doc.append(self.val) + 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 '##'") @@ -316,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-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_ From 76dd0f84974582311e4f5a763db68dea388d38b5 Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Mon, 10 Aug 2020 20:50:00 +0100 Subject: [PATCH 3/5] qapi/migration.json: Fix indentation Commits 6a9ad1542065ca0bd54c6 and 9004db48c080632aef23 added some new text to qapi/migration.json which doesn't fit the stricter indentation requirements imposed by the rST documentation generator. Reindent those lines to the new standard. Reviewed-by: Markus Armbruster Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell Message-Id: <20200810195019.25427-2-peter.maydell@linaro.org> Signed-off-by: Markus Armbruster --- qapi/migration.json | 60 ++++++++++++++++++++++----------------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/qapi/migration.json b/qapi/migration.json index 5f6b06172c..115181f4a5 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 From b2f1c13c31af2db759b7545cd8e8c525d6cb2e13 Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Mon, 10 Aug 2020 20:50:01 +0100 Subject: [PATCH 4/5] qapi: Fix indentation, again In commit 26ec4e53f2 and similar commits we fixed the indentation for doc comments in our qapi json files to follow a new stricter standard for indentation, which permits only: @arg: description line 1 description line 2 or: @arg: line 1 line 2 Unfortunately since we didn't manage to get the script changes that enforced the new style in, a variety of commits (eg df4097aeaf71, 2e4457032105) introduced new doc text which doesn't follow the new stricter rules for indentation on multi-line doc comments. Bring those into line with the new rules. Signed-off-by: Peter Maydell Message-Id: <20200810195019.25427-3-peter.maydell@linaro.org> Reviewed-by: Richard Henderson Signed-off-by: Markus Armbruster --- qapi/audio.json | 12 ++++++------ qapi/block-core.json | 8 ++++---- qapi/control.json | 4 ++-- qapi/machine.json | 6 +++--- qapi/migration.json | 8 ++++---- qapi/misc.json | 4 ++-- qapi/net.json | 2 +- 7 files changed, 22 insertions(+), 22 deletions(-) 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..091f826f53 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 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 115181f4a5..675f70bb67 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -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', From 6b306786cafd6ff939f1c831f0065c136105dca7 Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Mon, 10 Aug 2020 20:50:02 +0100 Subject: [PATCH 5/5] qapi/block-core.json: Fix nbd-server-start docs Commit eed8b6917832 added some new text to the nbd-server-start documentation in the wrong place. Since this is after the 'Returns:' line it's parsed as if it were part of the documentation of the "Returns:' information. Move it up to join the rest of the "documentation of the type as a whole" doc text. This doesn't look odd in the current HTML rendering, but the new QAPI-to-rST handling will complain about the indent level of the lines not matching up with the 'Returns:' line. Signed-off-by: Peter Maydell Message-Id: <20200810195019.25427-4-peter.maydell@linaro.org> Reviewed-by: Richard Henderson Signed-off-by: Markus Armbruster --- qapi/block-core.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 091f826f53..c5ac22d246 100644 --- a/qapi/block-core.json +++ b/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',