qapi qga/qapi-schema: Doc fixes
cover qapi qga/qapi-schema: Doc fixes
It's always nice to get doc fixes into the release, but if it's too late, it's too late.
Generated code does not change, except for the last patch, which moves a bit of code without changing it.
Markus Armbruster (16):
qga/qapi-schema: Tidy up documentation of guest-fsfreeze-status qga/qapi-schema: Fix a misspelled reference
qapi: Fix misspelled references
qapi: Fix up references to long gone error classes qapi/block-core: Clean up after removal of dirty bitmap @status
qapi: @foo should be used to reference, not ``foo``
qapi: Tidy up examples
qapi: Delete largely misleading "Stability Considerations"
qapi: Fix bullet list markup in documentation
qapi: Fix unintended definition lists in documentation qga/qapi-schema: Fix member documentation markup
qapi: Fix argument documentation markup
qapi: Replace ad hoc "since" documentation by member documentation
qapi: Fix misspelled section tags in doc comments
qapi: Format since information the conventional way: (since X.Y) qapi storage-daemon/qapi: Fix documentation section structure
docs/devel/qapi-code-gen.rst | 8 ++- docs/interop/firmware.json | 6 +- qapi/block-core.json | 82 ++++++++++++++-------------- qapi/block.json | 2 +- qapi/char.json | 4 +- qapi/control.json | 2 +- qapi/cryptodev.json | 4 ++ qapi/job.json | 4 +- qapi/machine-target.json | 2 +- qapi/machine.json | 26 +++++---- qapi/migration.json | 37 ++++++++----- qapi/misc.json | 6 +- qapi/net.json | 25 +++------ qapi/qapi-schema.json | 24 +------- qapi/qdev.json | 2 +- qapi/qom.json | 4 +- qapi/rdma.json | 2 +- qapi/replay.json | 3 + qapi/run-state.json | 6 +- qapi/stats.json | 3 +- qapi/tpm.json | 3 +- qapi/trace.json | 1 + qapi/ui.json | 12 ++-- qga/qapi-schema.json | 10 ++-- storage-daemon/qapi/qapi-schema.json | 22 +++++--- 25 files changed, 154 insertions(+), 146 deletions(-)
Signature · 1 line
2.39.2
PATCH 1/16 qga/qapi-schema: Tidy up documentation of guest-fsfreeze-status
Delete "error state indicates", because it doesn't make sense. I suspect it was an accident.
--- qga/qapi-schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
qga/qapi-schema.json +1 -1
@@ -420,7 +420,7 @@ ## # @guest-fsfreeze-status: # -# Get guest fsfreeze state. error state indicates +# Get guest fsfreeze state. # # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below) #
Signature · 1 line
2.39.2
Re: [PATCH 01/16] qga/qapi-schema: Tidy up documentation of guest-fsfreeze-status
Quoted 26 lines · Markus Armbruster
Delete "error state indicates", because it doesn't make sense. I suspect it was an accident.
Signed-off-by Markus Armbruster <[email protected]>--- qga/qapi-schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)qga/qapi-schema.json +1
-1@@ -420,7 +420,7 @@ ## # @guest-fsfreeze-status: # -# Get guest fsfreeze state. error state indicates +# Get guest fsfreeze state. # # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)#
--
2.39.2
PATCH 2/16 qga/qapi-schema: Fix a misspelled reference
In reply to Markus ArmbrusterCode returns a list of GuestNetworkInterface, documentation claims GuestNetworkInfo, which doesn't exist. Fix the documentation.
--- qga/qapi-schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
qga/qapi-schema.json +1 -1
@@ -722,7 +722,7 @@ # Get list of guest IP addresses, MAC addresses # and netmasks. # -# Returns: List of GuestNetworkInfo on success. +# Returns: List of GuestNetworkInterface on success. # # Since: 1.1 ##
Signature · 1 line
2.39.2
PATCH 3/16 qapi: Fix misspelled references
In reply to Markus Armbrusterquery-cpu-definitions returns a list of CpuDefinitionInfo, but documentation claims CpuDefInfo, which doesn't exist.
query-migrate-capabilities returns a list of MigrationCapabilityStatus, but documentation claims MigrationCapabilitiesStatus, which doesn't exist.
balloon and query-balloon can fail with KVMMissingCap, but documentation claims KvmMissingCap, which doesn't exist.
Fix the documentation.
--- qapi/machine-target.json | 2 +- qapi/machine.json | 4 ++-- qapi/migration.json | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-)
qapi/machine-target.json +1 -1
@@ -331,7 +331,7 @@ # # Return a list of supported virtual CPU definitions # -# Returns: a list of CpuDefInfo +# Returns: a list of CpuDefinitionInfo # # Since: 1.2 ##
qapi/machine.json +2 -2
@@ -1029,7 +1029,7 @@ # # Returns: - Nothing on success # - If the balloon driver is enabled but not functional because the KVM -# kernel module cannot support it, KvmMissingCap +# kernel module cannot support it, KVMMissingCap # - If no balloon device is present, DeviceNotActive # # Notes: This command just issues a request to the guest. When it returns,
@@ -1067,7 +1067,7 @@ # # Returns: - @BalloonInfo on success # - If the balloon driver is enabled but not functional because the KVM -# kernel module cannot support it, KvmMissingCap +# kernel module cannot support it, KVMMissingCap # - If no balloon device is present, DeviceNotActive # # Since: 0.14
qapi/migration.json +1 -1
@@ -531,7 +531,7 @@ # # Returns information about the current migration capabilities status # -# Returns: @MigrationCapabilitiesStatus +# Returns: @MigrationCapabilityStatus # # Since: 1.2 #
Signature · 1 line
2.39.2
Re: [PATCH 03/16] qapi: Fix misspelled references
Quoted 63 lines · Markus Armbruster
query-cpu-definitions returns a list of CpuDefinitionInfo, but documentation claims CpuDefInfo, which doesn't exist.
query-migrate-capabilities returns a list of MigrationCapabilityStatus, but documentation claims MigrationCapabilitiesStatus, which doesn't exist.
balloon and query-balloon can fail with KVMMissingCap, but documentation claims KvmMissingCap, which doesn't exist.
Fix the documentation.
Fixes e4e31c6324af (qapi: add query-cpu-definitions command (v2))Fixes bbf6da32b5bd (Add migration capabilities)Fixes d72f326431e2 (qapi: Convert balloon)Fixes 96637bcdf9e0 (qapi: Convert query-balloon)Signed-off-by Markus Armbruster <[email protected]>--- qapi/machine-target.json | 2 +- qapi/machine.json | 4 ++-- qapi/migration.json | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-)qapi/machine-target.json +1
-1@@ -331,7 +331,7 @@ # # Return a list of supported virtual CPU definitions # -# Returns: a list of CpuDefInfo +# Returns: a list of CpuDefinitionInfo # # Since: 1.2 ##qapi/machine.json +2
-2@@ -1029,7 +1029,7 @@ # # Returns: - Nothing on success # - If the balloon driver is enabled but not functional because the KVM -# kernel module cannot support it, KvmMissingCap +# kernel module cannot support it, KVMMissingCap # - If no balloon device is present, DeviceNotActive # # Notes: This command just issues a request to the guest. When it returns,@@ -1067,7 +1067,7 @@ # # Returns: - @BalloonInfo on success # - If the balloon driver is enabled but not functional because the KVM -# kernel module cannot support it, KvmMissingCap +# kernel module cannot support it, KVMMissingCap # - If no balloon device is present, DeviceNotActive # # Since: 0.14qapi/migration.json +0
-0
qapi/migration.json line 537
Quoted 8 lines
qapi/migration.json +1
-1@@ -531,7 +531,7 @@ # # Returns information about the current migration capabilities status # -# Returns: @MigrationCapabilitiesStatus +# Returns: @MigrationCapabilityStatus # # Since: 1.2 #
Signature · 3 lines
Thanks, David / dhildenb
PATCH 4/16 qapi: Fix up references to long gone error classes
In reply to Markus ArmbrusterCommit de253f14912e88f4 (qmp: switch to the new error format on the wire) removed most error classes. Several later commits mistakenly mentioned them in documentation. Replace them by the actual error class there.
--- qapi/block-core.json | 4 ++-- qapi/misc.json | 6 +++--- qapi/ui.json | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-)
qapi/block-core.json +2 -2
@@ -5784,7 +5784,7 @@ # - If any snapshot matching @name exists, or @name is empty, # GenericError # - If the format of the image used does not support it, -# BlockFormatFeatureNotSupported +# GenericError # # Since: 1.7 #
@@ -5820,7 +5820,7 @@ # - If @device is not a valid block device, GenericError # - If snapshot not found, GenericError # - If the format of the image used does not support it, -# BlockFormatFeatureNotSupported +# GenericError # - If @id and @name are both not specified, GenericError # # Since: 1.7
qapi/misc.json +3 -3
@@ -349,8 +349,8 @@ # @opaque: A free-form string that can be used to describe the fd. # # Returns: - @AddfdInfo on success -# - If file descriptor was not received, FdNotSupplied -# - If @fdset-id is a negative value, InvalidParameterValue +# - If file descriptor was not received, GenericError +# - If @fdset-id is a negative value, GenericError # # Notes: The list of fd sets is shared by all monitor connections. #
@@ -379,7 +379,7 @@ # @fd: The file descriptor that is to be removed. # # Returns: - Nothing on success -# - If @fdset-id or @fd is not found, FdNotFound +# - If @fdset-id or @fd is not found, GenericError # # Since: 1.2 #
qapi/ui.json +1 -1
@@ -985,7 +985,7 @@ # to 100 # # Returns: - Nothing on success -# - If key is unknown or redundant, InvalidParameter +# - If key is unknown or redundant, GenericError # # Since: 1.3 #
Signature · 1 line
2.39.2
PATCH 5/16 qapi/block-core: Clean up after removal of dirty bitmap @status
In reply to Markus ArmbrusterCommit 81cbfd50886 (block: remove dirty bitmaps 'status' field) removed deprecated BlockDirtyInfo member @status. It neglected to remove references to its enumeration values from the documentation of its replacements. Do that now.
--- qapi/block-core.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
qapi/block-core.json +2 -2
@@ -582,11 +582,11 @@ # @granularity: granularity of the dirty bitmap in bytes (since 1.4) # # @recording: true if the bitmap is recording new writes from the guest. -# Replaces ``active`` and ``disabled`` statuses. (since 4.0) +# (since 4.0) # # @busy: true if the bitmap is in-use by some operation (NBD or jobs) # and cannot be modified via QMP or used by another operation. -# Replaces ``locked`` and ``frozen`` statuses. (since 4.0) +# (since 4.0) # # @persistent: true if the bitmap was stored on disk, is scheduled to be stored # on disk, or both. (since 4.0)
Signature · 1 line
2.39.2
Re: [PATCH 05/16] qapi/block-core: Clean up after removal of dirty bitmap @status
Quoted 30 lines · Markus Armbruster
Commit
81cbfd50886(block: remove dirty bitmaps 'status' field) removed deprecated BlockDirtyInfo member @status. It neglected to remove references to its enumeration values from the documentation of its replacements. Do that now.Signed-off-by Markus Armbruster <[email protected]>--- qapi/block-core.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)qapi/block-core.json +2
-3@@ -582,11 +582,11 @@ # @granularity: granularity of the dirty bitmap in bytes (since 1.4) # # @recording: true if the bitmap is recording new writes from the guest. -# Replaces ``active`` and ``disabled`` statuses. (since 4.0) +# (since 4.0) # # @busy: true if the bitmap is in-use by some operation (NBD or jobs) # and cannot be modified via QMP or used by another operation. -# Replaces ``locked`` and ``frozen`` statuses. (since 4.0) +# (since 4.0) # # @persistent: true if the bitmap was stored on disk, is scheduled to be stored # on disk, or both. (since 4.0) --
Quoted 2 lines
2.39.2
PATCH 6/16 qapi: @foo should be used to reference, not ``foo``
In reply to Markus ArmbrusterDocumentation suggests @foo is merely shorthand for ``foo``. It's not, it carries additional meaning: it's a reference to a QAPI schema name.
Reword the documentation to spell that out.
Fix up the few ``foo`` that should be @foo.
--- docs/devel/qapi-code-gen.rst | 8 +++++--- docs/interop/firmware.json | 6 +++--- qapi/qom.json | 2 +- qapi/ui.json | 2 +- 4 files changed, 10 insertions(+), 8 deletions(-)
docs/devel/qapi-code-gen.rst +5 -3
@@ -925,9 +925,11 @@ first character of the first line. The usual ****strong****, *\*emphasized\** and ````literal```` markup should be used. If you need a single literal ``*``, you will need to -backslash-escape it. As an extension beyond the usual rST syntax, you -can also use ``@foo`` to reference a name in the schema; this is rendered -the same way as ````foo````. +backslash-escape it. + +Use ``@foo`` to reference a name in the schema. This is an rST +extension. It is rendered the same way as ````foo````, but carries +additional meaning. Example::
docs/interop/firmware.json +3 -3
@@ -258,7 +258,7 @@ # # @mode: Describes how the firmware build handles code versus variable # storage. If not present, it must be treated as if it was -# configured with value ``split``. Since: 7.0.0 +# configured with value @split. Since: 7.0.0 # # @executable: Identifies the firmware executable. The @mode # indicates whether there will be an associated
@@ -267,13 +267,13 @@ # -drive if=none,id=pflash0,readonly=on,file=@executable.@filename,format=@executable.@format # -machine pflash0=pflash0 # or equivalent -blockdev instead of -drive. When -# @mode is ``combined`` the executable must be +# @mode is @combined the executable must be # cloned before use and configured with readonly=off. # With QEMU versions older than 4.0, you have to use # -drive if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executable.@format # # @nvram-template: Identifies the NVRAM template compatible with -# @executable, when @mode is set to ``split``, +# @executable, when @mode is set to @split, # otherwise it should not be present. # Management software instantiates an # individual copy -- a specific NVRAM file -- from
qapi/qom.json +1 -1
@@ -637,7 +637,7 @@ # # @discard-data: if true, the file contents can be destroyed when QEMU exits, # to avoid unnecessarily flushing data to the backing file. Note -# that ``discard-data`` is only an optimization, and QEMU might +# that @discard-data is only an optimization, and QEMU might # not discard file contents if it aborts unexpectedly or is # terminated using SIGKILL. (default: false) #
qapi/ui.json +1 -1
@@ -1247,7 +1247,7 @@ # available node on the host. # # @p2p: Whether to use peer-to-peer connections (accepted through -# ``add_client``). +# @add_client). # # @audiodev: Use the specified DBus audiodev to export audio. #
Signature · 1 line
2.39.2
PATCH 7/16 qapi: Tidy up examples
In reply to Markus ArmbrusterA few examples neglect to prefix QMP input with '->'. Fix that.
A few examples neglect to show output. Provide some. The example output for query-vcpu-dirty-limit could use further improvement. Add a TODO comment.
Use "Examples:" instead of "Example:" where multiple examples are given.
One example section numbers its two examples. Not done elswehre; drop.
Another example section separates them with "or". Likewise.
--- qapi/block-core.json | 14 ++++++-------- qapi/block.json | 2 +- qapi/char.json | 4 ++-- qapi/machine.json | 7 ++++--- qapi/migration.json | 33 ++++++++++++++++++++++----------- qapi/net.json | 4 +--- qapi/qdev.json | 2 +- qapi/qom.json | 2 +- qapi/replay.json | 3 +++ qapi/ui.json | 2 +- 10 files changed, 42 insertions(+), 31 deletions(-)
qapi/block-core.json +6 -8
@@ -4574,9 +4574,8 @@ # # Since: 2.9 # -# Example: +# Examples: # -# 1. # -> { "execute": "blockdev-add", # "arguments": { # "driver": "qcow2",
@@ -4589,7 +4588,6 @@ # } # <- { "return": {} } # -# 2. # -> { "execute": "blockdev-add", # "arguments": { # "driver": "qcow2",
@@ -5596,7 +5594,7 @@ # # Since: 2.7 # -# Example: +# Examples: # # 1. Add a new node to a quorum # -> { "execute": "blockdev-add",
@@ -5646,7 +5644,7 @@ # # Since: 2.12 # -# Example: +# Examples: # # 1. Move a node into an IOThread # -> { "execute": "x-blockdev-set-iothread",
@@ -5731,18 +5729,18 @@ # # Since: 2.0 # -# Example: +# Examples: # # 1. Read operation # -# { "event": "QUORUM_REPORT_BAD", +# <- { "event": "QUORUM_REPORT_BAD", # "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5, # "type": "read" }, # "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } # # 2. Flush operation # -# { "event": "QUORUM_REPORT_BAD", +# <- { "event": "QUORUM_REPORT_BAD", # "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120, # "type": "flush", "error": "Broken pipe" }, # "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
qapi/block.json +1 -1
@@ -457,7 +457,7 @@ # # Since: 1.1 # -# Example: +# Examples: # # -> { "execute": "block_set_io_throttle", # "arguments": { "id": "virtio-blk-pci0/virtio-backend",
qapi/char.json +2 -2
@@ -637,7 +637,7 @@ # # Since: 1.4 # -# Example: +# Examples: # # -> { "execute" : "chardev-add", # "arguments" : { "id" : "foo",
@@ -673,7 +673,7 @@ # # Since: 2.10 # -# Example: +# Examples: # # -> { "execute" : "chardev-change", # "arguments" : { "id" : "baz",
qapi/machine.json +4 -3
@@ -954,7 +954,7 @@ # # Since: 2.7 # -# Example: +# Examples: # # For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8: #
@@ -1677,8 +1677,9 @@ # Since: 7.2 # # Example: -# {"execute": "dumpdtb"} -# "arguments": { "filename": "fdt.dtb" } } +# -> { "execute": "dumpdtb" } +# "arguments": { "filename": "fdt.dtb" } } +# <- { "return": {} } # ## { 'command': 'dumpdtb',
qapi/migration.json +22 -11
@@ -273,7 +273,7 @@ # # Since: 0.14 # -# Example: +# Examples: # # 1. Before the first migration #
@@ -521,6 +521,7 @@ # # -> { "execute": "migrate-set-capabilities" , "arguments": # { "capabilities": [ { "capability": "xbzrle", "state": true } ] } } +# <- { "return": {} } # ## { 'command': 'migrate-set-capabilities',
@@ -989,6 +990,7 @@ # # -> { "execute": "migrate-set-parameters" , # "arguments": { "compress-level": 1 } } +# <- { "return": {} } # ## { 'command': 'migrate-set-parameters', 'boxed': true,
@@ -1279,8 +1281,8 @@ # # Example: # -# { "timestamp": {"seconds": 1449669631, "microseconds": 239225}, -# "event": "MIGRATION_PASS", "data": {"pass": 2} } +# <- { "timestamp": {"seconds": 1449669631, "microseconds": 239225}, +# "event": "MIGRATION_PASS", "data": {"pass": 2} } # ## { 'event': 'MIGRATION_PASS',
@@ -1861,8 +1863,9 @@ # # Example: # -# {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, -# 'sample-pages': 512} } +# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, +# 'sample-pages': 512} } +# <- { "return": {} } # ## { 'command': 'calc-dirty-rate', 'data': {'calc-time': 'int64',
@@ -1914,9 +1917,11 @@ # Since: 7.1 # # Example: -# {"execute": "set-vcpu-dirty-limit"} -# "arguments": { "dirty-rate": 200, -# "cpu-index": 1 } } +# +# -> {"execute": "set-vcpu-dirty-limit"} +# "arguments": { "dirty-rate": 200, +# "cpu-index": 1 } } +# <- { "return": {} } # ## { 'command': 'set-vcpu-dirty-limit',
@@ -1937,8 +1942,10 @@ # Since: 7.1 # # Example: -# {"execute": "cancel-vcpu-dirty-limit"} -# "arguments": { "cpu-index": 1 } } +# +# -> {"execute": "cancel-vcpu-dirty-limit"}, +# "arguments": { "cpu-index": 1 } } +# <- { "return": {} } # ## { 'command': 'cancel-vcpu-dirty-limit',
@@ -1952,7 +1959,11 @@ # Since: 7.1 # # Example: -# {"execute": "query-vcpu-dirty-limit"} +# +# -> {"execute": "query-vcpu-dirty-limit"} +# <- {"return": [ +# { "limit-rate": 60, "current-rate": 3, "cpu-index": 0}, +# { "limit-rate": 60, "current-rate": 3, "cpu-index": 1}]} # ## { 'command': 'query-vcpu-dirty-limit',
qapi/net.json +1 -3
@@ -914,7 +914,7 @@ # # Since: 7.2 # -# Example: +# Examples: # # <- { "event": "NETDEV_STREAM_CONNECTED", # "data": { "netdev-id": "netdev0",
@@ -922,8 +922,6 @@ # "host": "::1", "type": "inet" } }, # "timestamp": { "seconds": 1666269863, "microseconds": 311222 } } # -# or -# # <- { "event": "NETDEV_STREAM_CONNECTED", # "data": { "netdev-id": "netdev0", # "addr": { "path": "/tmp/qemu0", "type": "unix" } },
qapi/qdev.json +1 -1
@@ -100,7 +100,7 @@ # # Since: 0.14 # -# Example: +# Examples: # # -> { "execute": "device_del", # "arguments": { "id": "net1" } }
qapi/qom.json +1 -1
@@ -103,7 +103,7 @@ # # Since: 1.2 # -# Example: +# Examples: # # 1. Use absolute path #
qapi/replay.json +3 -0
@@ -81,6 +81,7 @@ # Example: # # -> { "execute": "replay-break", "arguments": { "icount": 220414 } } +# <- { "return": {} } # ## { 'command': 'replay-break', 'data': { 'icount': 'int' } }
@@ -96,6 +97,7 @@ # Example: # # -> { "execute": "replay-delete-break" } +# <- { "return": {} } # ## { 'command': 'replay-delete-break' }
@@ -117,5 +119,6 @@ # Example: # # -> { "execute": "replay-seek", "arguments": { "icount": 220414 } } +# <- { "return": {} } ## { 'command': 'replay-seek', 'data': { 'icount': 'int' } }
qapi/ui.json +1 -1
@@ -1153,7 +1153,7 @@ # so it is possible to map which console belongs to which device and # display. # -# Example: +# Examples: # # 1. Press left mouse button. #
Signature · 1 line
2.39.2
PATCH 8/16 qapi: Delete largely misleading "Stability Considerations"
In reply to Markus ArmbrusterDocumentation section "Stability Considerations" dates back to the early days of QMP (commit 82a56f0d83d (Monitor: Introduce the qmp-commands.hx file)). It became largely misleading years ago. Delete it.
--- qapi/qapi-schema.json | 22 ---------------------- 1 file changed, 22 deletions(-)
qapi/qapi-schema.json +0 -22
@@ -28,28 +28,6 @@ # # Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for # detailed information on the Server command and response formats. -# -# = Stability Considerations -# -# The current QMP command set (described in this file) may be useful for a -# number of use cases, however it's limited and several commands have bad -# defined semantics, specially with regard to command completion. -# -# These problems are going to be solved incrementally in the next QEMU releases -# and we're going to establish a deprecation policy for badly defined commands. -# -# If you're planning to adopt QMP, please observe the following: -# -# 1. The deprecation policy will take effect and be documented soon, please -# check the documentation of each used command as soon as a new release of -# QEMU is available -# -# 2. DO NOT rely on anything which is not explicit documented -# -# 3. Errors, in special, are not documented. Applications should NOT check -# for specific errors classes or data (it's strongly recommended to only -# check for the "error" key) -# ## { 'include': 'pragma.json' }
Signature · 1 line
2.39.2
PATCH 9/16 qapi: Fix bullet list markup in documentation
In reply to Markus ArmbrusterPeter Maydell's commit 100cc4fe0f08 explains:
rST insists on a blank line before and after a bulleted list [...] Add some extra blank lines in the doc comments so they're acceptable rST input.
It missed one in qapi/trace.json.
Paolo Bonzini later added another instance in qapi/stats.json, providing further, if unintended, evidence for his quip that rST is the Perl of ASCII-based markups.
Both are parsed as ordinary paragraph, resulting in garbled output.
Add the blank lines we need to get the bullet lists recognized as such.
--- qapi/stats.json | 1 + qapi/trace.json | 1 + 2 files changed, 2 insertions(+)
qapi/stats.json +1 -0
@@ -107,6 +107,7 @@ # The arguments to the query-stats command; specifies a target for which to # request statistics and optionally the required subset of information for # that target: +# # - which vCPUs to request statistics for # - which providers to request statistics from # - which named values to return within each provider
qapi/trace.json +1 -0
@@ -87,6 +87,7 @@ # @vcpu: The vCPU to act upon (all by default; since 2.7). # # An event's state is modified if: +# # - its name matches the @name pattern, and # - if @vcpu is given, the event has the "vcpu" property. #
Signature · 1 line
2.39.2
PATCH 10/16 qapi: Fix unintended definition lists in documentation
In reply to Markus ArmbrusterrST parses something like
first line
second line
as a definition list item, where "first line" is the term being defined by "second line".
This bites us in a couple of places. Here's one:
# @bps_max: total throughput limit during bursts,
# in bytes (Since 1.7)
scripts/qapi/parser.py parses this into an "argument section" with name "bps_max" and text
total throughput limit during bursts,
in bytes (Since 1.7)
docs/sphinx/qapidoc.py duly passes the text to the rST parser, which parses it as another definition list. Comes out as nested
definitions: term "bps_max: int (optional)" defined as term "total throughput limit during bursts," defined as "in bytes (Since 1.7)".
rST truly is the Perl of ASCII-based markups.
Fix by deleting the extra indentation.
--- qapi/block-core.json | 52 ++++++++++++++++++++++---------------------- qapi/control.json | 2 +- 2 files changed, 27 insertions(+), 27 deletions(-)
qapi/block-core.json +26 -26
@@ -488,41 +488,41 @@ # # @image: the info of image used (since: 1.6) # -# @bps_max: total throughput limit during bursts, -# in bytes (Since 1.7) +# @bps_max: total throughput limit during bursts, in bytes +# (Since 1.7) # -# @bps_rd_max: read throughput limit during bursts, -# in bytes (Since 1.7) +# @bps_rd_max: read throughput limit during bursts, in bytes +# (Since 1.7) # -# @bps_wr_max: write throughput limit during bursts, -# in bytes (Since 1.7) +# @bps_wr_max: write throughput limit during bursts, in bytes +# (Since 1.7) # -# @iops_max: total I/O operations per second during bursts, -# in bytes (Since 1.7) +# @iops_max: total I/O operations per second during bursts, in bytes +# (Since 1.7) # -# @iops_rd_max: read I/O operations per second during bursts, -# in bytes (Since 1.7) +# @iops_rd_max: read I/O operations per second during bursts, in bytes +# (Since 1.7) # -# @iops_wr_max: write I/O operations per second during bursts, -# in bytes (Since 1.7) +# @iops_wr_max: write I/O operations per second during bursts, in +# bytes (Since 1.7) # -# @bps_max_length: maximum length of the @bps_max burst -# period, in seconds. (Since 2.6) +# @bps_max_length: maximum length of the @bps_max burst period, in +# seconds. (Since 2.6) # -# @bps_rd_max_length: maximum length of the @bps_rd_max -# burst period, in seconds. (Since 2.6) +# @bps_rd_max_length: maximum length of the @bps_rd_max burst period, +# in seconds. (Since 2.6) # -# @bps_wr_max_length: maximum length of the @bps_wr_max -# burst period, in seconds. (Since 2.6) +# @bps_wr_max_length: maximum length of the @bps_wr_max burst period, +# in seconds. (Since 2.6) # -# @iops_max_length: maximum length of the @iops burst -# period, in seconds. (Since 2.6) +# @iops_max_length: maximum length of the @iops burst period, in +# seconds. (Since 2.6) # -# @iops_rd_max_length: maximum length of the @iops_rd_max -# burst period, in seconds. (Since 2.6) +# @iops_rd_max_length: maximum length of the @iops_rd_max burst +# period, in seconds. (Since 2.6) # -# @iops_wr_max_length: maximum length of the @iops_wr_max -# burst period, in seconds. (Since 2.6) +# @iops_wr_max_length: maximum length of the @iops_wr_max burst +# period, in seconds. (Since 2.6) # # @iops_size: an I/O size in bytes (Since 1.7) #
@@ -948,7 +948,7 @@ # by the device (Since 4.2) # # @invalid_rd_operations: The number of invalid read operations -# performed by the device (Since 2.5) +# performed by the device (Since 2.5) # # @invalid_wr_operations: The number of invalid write operations # performed by the device (Since 2.5)
@@ -3735,7 +3735,7 @@ # Driver specific block device options for Quorum # # @blkverify: true if the driver must print content mismatch -# set to false by default +# set to false by default # # @children: the children block devices to use #
qapi/control.json +1 -1
@@ -195,7 +195,7 @@ # @id: Name of the monitor # # @mode: Selects the monitor mode (default: readline in the system -# emulator, control in qemu-storage-daemon) +# emulator, control in qemu-storage-daemon) # # @pretty: Enables pretty printing (QMP only) #
Signature · 1 line
2.39.2
Re: [PATCH 10/16] qapi: Fix unintended definition lists in documentation
Quoted 25 lines · Markus Armbruster
rST parses something like
first line
second lineas a definition list item, where "first line" is the term being defined by "second line".
This bites us in a couple of places. Here's one:
# @bps_max: total throughput limit during bursts,
# in bytes (Since 1.7)
scripts/qapi/parser.pyparses this into an "argument section" with name "bps_max" and texttotal throughput limit during bursts,
in bytes (Since 1.7)
docs/sphinx/qapidoc.pyduly passes the text to the rST parser, which parses it as another definition list. Comes out as nested
definitions: term "bps_max: int (optional)" defined as term "total throughput limit during bursts," defined as "in bytes (Since 1.7)".
Quoted 6 lines
rST truly is the Perl of ASCII-based markups.
Fix by deleting the extra indentation.
Reported-by Peter Maydell <[email protected]>Signed-off-by Markus Armbruster <[email protected]>
thanks
-- PMM
PATCH 11/16 qga/qapi-schema: Fix member documentation markup
In reply to Markus ArmbrusterGuestDiskStatsInfo's member documentation is parsed as ordinary text due to missing colons. The generated documentation shows these members as "Not documented".
The fix is obvious: add the missing colons.
--- qga/qapi-schema.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
qga/qapi-schema.json +3 -3
@@ -1553,11 +1553,11 @@ ## # @GuestDiskStatsInfo: # -# @name disk name +# @name: disk name # -# @major major device number of disk +# @major: major device number of disk # -# @minor minor device number of disk +# @minor: minor device number of disk ## { 'struct': 'GuestDiskStatsInfo', 'data': {'name': 'str',
Signature · 1 line
2.39.2
PATCH 12/16 qapi: Fix argument documentation markup
In reply to Markus ArmbrusterMember / argument documentation of BlockdevAmendOptionsQcow2, job-resume, and RDMA_GID_STATUS_CHANGED is parsed as ordinary text due to missing colon or space before the colon. The generated documentation shows these members / arguments as "Not documented".
The fix is obvious: add missing colons, delete extra spaces.
--- qapi/block-core.json | 2 +- qapi/job.json | 2 +- qapi/rdma.json | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-)
qapi/block-core.json +1 -1
@@ -5155,7 +5155,7 @@ # Driver specific image amend options for qcow2. # For now, only encryption options can be amended # -# @encrypt Encryption options to be amended +# @encrypt: Encryption options to be amended # # Since: 5.1 ##
qapi/job.json +1 -1
@@ -148,7 +148,7 @@ # This command returns immediately after resuming a paused job. Resuming an # already running job is an error. # -# @id : The job identifier. +# @id: The job identifier. # # Since: 3.0 ##
qapi/rdma.json +1 -1
@@ -17,7 +17,7 @@ # # @subnet-prefix: Subnet Prefix # -# @interface-id : Interface ID +# @interface-id: Interface ID # # Since: 4.0 #
Signature · 1 line
2.39.2
PATCH 13/16 qapi: Replace ad hoc "since" documentation by member documentation
In reply to Markus ArmbrusterMemoryDeviceInfoKind, NetClientDriver, and GuestPanicAction mention some members only in ad hoc since documentation. The generated documentation shows these members as "Not documented".
Replace by formal member documentation.
Add actual documentation text for the GuestPanicAction members, to match existing member documentation there. For the others, merely move existing "since" information.
--- qapi/machine.json | 11 ++++++++--- qapi/net.json | 21 ++++++++------------- qapi/run-state.json | 6 +++++- 3 files changed, 21 insertions(+), 17 deletions(-)
qapi/machine.json +8 -3
@@ -1260,6 +1260,14 @@ ## # @MemoryDeviceInfoKind: # +# @nvdimm: since 2.12 +# +# @virtio-pmem: since 4.1 +# +# @virtio-mem: since 5.1 +# +# @sgx-epc: since 6.2. +# # Since: 2.1 ## { 'enum': 'MemoryDeviceInfoKind',
@@ -1302,9 +1310,6 @@ # # Union containing information about a memory device # -# nvdimm is included since 2.12. virtio-pmem is included since 4.1. -# virtio-mem is included since 5.1. sgx-epc is included since 6.2. -# # Since: 2.1 ## { 'union': 'MemoryDeviceInfo',
qapi/net.json +8 -13
@@ -641,14 +641,15 @@ # # Available netdev drivers. # -# Since: 2.7 +# @l2tpv3: since 2.1 +# @vhost-vdpa: since 5.1 +# @vmnet-host: since 7.1 +# @vmnet-shared: since 7.1 +# @vmnet-bridged: since 7.1 +# @stream: since 7.2 +# @dgram: since 7.2 # -# @vhost-vdpa since 5.1 -# @vmnet-host since 7.1 -# @vmnet-shared since 7.1 -# @vmnet-bridged since 7.1 -# @stream since 7.2 -# @dgram since 7.2 +# Since: 2.7 ## { 'enum': 'NetClientDriver', 'data': [ 'none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'stream',
@@ -669,12 +670,6 @@ # # Since: 1.2 # -# 'l2tpv3' - since 2.1 -# 'vmnet-host' - since 7.1 -# 'vmnet-shared' - since 7.1 -# 'vmnet-bridged' - since 7.1 -# 'stream' since 7.2 -# 'dgram' since 7.2 ## { 'union': 'Netdev', 'base': { 'id': 'str', 'type': 'NetClientDriver' },
qapi/run-state.json +5 -1
@@ -468,7 +468,11 @@ # # @pause: system pauses # -# Since: 2.1 (poweroff since 2.8, run since 5.0) +# @poweroff: system powers off (since 2.8) +# +# @run: system continues to run (since 5.0) +# +# Since: 2.1 ## { 'enum': 'GuestPanicAction', 'data': [ 'pause', 'poweroff', 'run' ] }
Signature · 1 line
2.39.2
PATCH 14/16 qapi: Fix misspelled section tags in doc comments
In reply to Markus ArmbrusterSection tags are case sensitive and end with a colon. Screwing up either gets them interpreted as ordinary paragraph. Fix a few.
--- qapi/machine.json | 4 ++-- qapi/migration.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-)
qapi/machine.json +2 -2
@@ -517,7 +517,7 @@ # @targets: Target root bridge IDs from -device ...,id=<ID> for each root # bridge. # -# Since 7.1 +# Since: 7.1 ## { 'struct': 'CXLFixedMemoryWindowOptions', 'data': {
@@ -532,7 +532,7 @@ # # @cxl-fmw: List of CXLFixedMemoryWindowOptions # -# Since 7.1 +# Since: 7.1 ## { 'struct' : 'CXLFMWProperties', 'data': { 'cxl-fmw': ['CXLFixedMemoryWindowOptions'] }
qapi/migration.json +1 -1
@@ -1991,7 +1991,7 @@ # # data: migration thread name # -# returns: information about migration threads +# Returns: information about migration threads # # Since: 7.2 ##
Signature · 1 line
2.39.2
PATCH 15/16 qapi: Format since information the conventional way: (since X.Y)
In reply to Markus Armbruster--- qapi/block-core.json | 6 +++--- qapi/stats.json | 2 +- qapi/tpm.json | 3 +-- qapi/ui.json | 6 +++--- 4 files changed, 8 insertions(+), 9 deletions(-)
qapi/block-core.json +3 -3
@@ -1318,10 +1318,10 @@ # value is monotonically increasing. # # @busy: false if the job is known to be in a quiescent state, with -# no pending I/O. Since 1.3. +# no pending I/O. (Since 1.3) # # @paused: whether the job is paused or, if @busy is true, will -# pause itself as soon as possible. Since 1.3. +# pause itself as soon as possible. (Since 1.3) # # @speed: the rate limit, bytes per second #
@@ -2741,7 +2741,7 @@ # # @on-error: the action to take on an error (default report). # 'stop' and 'enospc' can only be used if the block device -# supports io-status (see BlockInfo). Since 1.3. +# supports io-status (see BlockInfo). (Since 1.3) # # @filter-node-name: the node name that should be assigned to the # filter driver that the stream job inserts into the graph
qapi/stats.json +1 -1
@@ -69,7 +69,7 @@ # # @vcpu: statistics that apply to a single virtual CPU. # -# @cryptodev: statistics that apply to a crypto device. since 8.0 +# @cryptodev: statistics that apply to a crypto device (since 8.0) # # Since: 7.1 ##
qapi/tpm.json +1 -2
@@ -44,8 +44,7 @@ # An enumeration of TPM types # # @passthrough: TPM passthrough type -# @emulator: Software Emulator TPM type -# Since: 2.11 +# @emulator: Software Emulator TPM type (since 2.11) # # Since: 1.5 ##
qapi/ui.json +3 -3
@@ -1207,13 +1207,13 @@ # window resizes (virtio-gpu) this will default to "on", # assuming the guest will resize the display to match # the window size then. Otherwise it defaults to "off". -# Since 3.1 +# (Since 3.1) # @show-tabs: Display the tab bar for switching between the various graphical # interfaces (e.g. VGA and virtual console character devices) # by default. -# Since 7.1 +# (Since 7.1) # @show-menubar: Display the main window menubar. Defaults to "on". -# Since 8.0 +# (Since 8.0) # # Since: 2.12 ##
Signature · 1 line
2.39.2
Re: [PATCH 15/16] qapi: Format since information the conventional way: (since X.Y)
Quoted 27 lines · Markus Armbruster
qapi/block-core.json +1
-1@@ -2741,7 +2741,7 @@ # # @on-error: the action to take on an error (default report). # 'stop' and 'enospc' can only be used if the block device -# supports io-status (see BlockInfo). Since 1.3. +# supports io-status (see BlockInfo). (Since 1.3) # # @filter-node-name: the node name that should be assigned to the # filter driver that the stream job inserts into the graphqapi/stats.json +1
-1@@ -69,7 +69,7 @@ # # @vcpu: statistics that apply to a single virtual CPU. # -# @cryptodev: statistics that apply to a crypto device. since 8.0 +# @cryptodev: statistics that apply to a crypto device (since 8.0) # # Since: 7.1 ##qapi/tpm.json +0
-0
qapi/tpm.json line 47
Quoted 6 lines
qapi/tpm.json +1
-2@@ -44,8 +44,7 @@ # An enumeration of TPM types # # @passthrough: TPM passthrough type -# @emulator: Software Emulator TPM type -# Since: 2.11 +# @emulator: Software Emulator TPM type (since 2.11)
Seems, we don't have any preference between "some text (since VER)" vs "some text. (Since VER)" ?
Signature · 2 lines
Best regards, Vladimir
Re: [PATCH 15/16] qapi: Format since information the conventional way: (since X.Y)
Quoted 28 lines · Vladimir Sementsov-Ogievskiy
Quoted 27 lines · Markus Armbruster
qapi/block-core.json +1
-1@@ -2741,7 +2741,7 @@ # # @on-error: the action to take on an error (default report). # 'stop' and 'enospc' can only be used if the block device -# supports io-status (see BlockInfo). Since 1.3. +# supports io-status (see BlockInfo). (Since 1.3) # # @filter-node-name: the node name that should be assigned to the # filter driver that the stream job inserts into the graphqapi/stats.json +1
-1@@ -69,7 +69,7 @@ # # @vcpu: statistics that apply to a single virtual CPU. # -# @cryptodev: statistics that apply to a crypto device. since 8.0 +# @cryptodev: statistics that apply to a crypto device (since 8.0) # # Since: 7.1 ##qapi/tpm.json +0
-0@@ -44,8 +44,7 @@
Quoted 8 lines
qapi/tpm.json line 47
Quoted 6 lines
qapi/tpm.json +1
-2# An enumeration of TPM types # # @passthrough: TPM passthrough type -# @emulator: Software Emulator TPM type -# Since: 2.11 +# @emulator: Software Emulator TPM type (since 2.11)Seems, we don't have any preference between "some text (since VER)" vs "some text. (Since VER)" ?
I personally use (Since VER) after a full sentence ending in punctuation, and (since VER) after something that doesn't end in punctuation.
PATCH 16/16 qapi storage-daemon/qapi: Fix documentation section structure
In reply to Markus ArmbrusterIn the QEMU QMP Reference Manual, subsection "Block core (VM unrelated)" is empty. Its contents is at the end of subsection "Background jobs" instead. That's because qapi/job.json is includeded first from qapi/block-core.json, which makes qapi/job.json's documentation go between qapi/block-core.json's subsection heading and contents.
In the QEMU Storage Daemon QMP Reference Manual, section "Block Devices" contains nothing but an empty subsection "Block core (VM unrelated)". The latter's contents is at the end section "Socket data types", along with subsection "Block device exports". Subsection "Background jobs" is at the end of section "Cryptography". All this is because storage-daemon/qapi/qapi-schema.json includes modules in a confused order.
Fix both as follows.
Turn subsection "Background jobs" into a section.
Move it before section "Block devices" in the QEMU QMP Reference Manual, by including qapi/jobs.json right before qapi/block.json.
Reorder include directives in storage-daemon/qapi/qapi-schema.json to match the order in qapi/qapi-schema.json, so that the QEMU Storage Daemon QMP Reference Manual's section structure the QEMU QMP Reference Manual's.
In the QEMU QMP Reference Manual, qapi/cryptodev.json's documentation is at the end of section "Virtio devices". That's because it lacks a section heading, and therefore gets squashed into whatever section happens to precede it.
Add section heading so it's in section "Cryptography devices".
--- qapi/cryptodev.json | 4 ++++ qapi/job.json | 2 +- qapi/qapi-schema.json | 2 +- storage-daemon/qapi/qapi-schema.json | 22 +++++++++++++++------- 4 files changed, 21 insertions(+), 9 deletions(-)
qapi/cryptodev.json +4 -0
@@ -4,6 +4,10 @@ # This work is licensed under the terms of the GNU GPL, version 2 or later. # See the COPYING file in the top-level directory. +## +# = Cryptography devices +## + ## # @QCryptodevBackendAlgType: #
qapi/job.json +1 -1
@@ -2,7 +2,7 @@ # vim: filetype=python ## -# == Background jobs +# = Background jobs ## ##
qapi/qapi-schema.json +1 -1
@@ -43,11 +43,11 @@ { 'include': 'sockets.json' } { 'include': 'run-state.json' } { 'include': 'crypto.json' } +{ 'include': 'job.json' } { 'include': 'block.json' } { 'include': 'block-export.json' } { 'include': 'char.json' } { 'include': 'dump.json' } -{ 'include': 'job.json' } { 'include': 'net.json' } { 'include': 'rdma.json' } { 'include': 'rocker.json' }
storage-daemon/qapi/qapi-schema.json +15 -7
@@ -15,18 +15,26 @@ { 'include': '../../qapi/pragma.json' } +# Documentation generated with qapi-gen.py is in source order, with +# included sub-schemas inserted at the first include directive +# (subsequent include directives have no effect). To get a sane and +# stable order, it's best to include each sub-schema just once, or +# include it first right here. + +{ 'include': '../../qapi/common.json' } +{ 'include': '../../qapi/sockets.json' } +{ 'include': '../../qapi/crypto.json' } +{ 'include': '../../qapi/job.json' } + ## # = Block devices ## { 'include': '../../qapi/block-core.json' } { 'include': '../../qapi/block-export.json' } + { 'include': '../../qapi/char.json' } -{ 'include': '../../qapi/common.json' } -{ 'include': '../../qapi/control.json' } -{ 'include': '../../qapi/crypto.json' } -{ 'include': '../../qapi/introspect.json' } -{ 'include': '../../qapi/job.json' } { 'include': '../../qapi/authz.json' } -{ 'include': '../../qapi/qom.json' } -{ 'include': '../../qapi/sockets.json' } { 'include': '../../qapi/transaction.json' } +{ 'include': '../../qapi/control.json' } +{ 'include': '../../qapi/introspect.json' } +{ 'include': '../../qapi/qom.json' }
Signature · 1 line
2.39.2
Re: [PATCH 16/16] qapi storage-daemon/qapi: Fix documentation section structure
Quoted 3 lines · Markus Armbruster
In the QEMU QMP Reference Manual, subsection "Block core (VM unrelated)" is empty. Its contents is at the end of subsection "Background jobs" instead. That's because
qapi/job.jsonis includeded
included
Quoted 31 lines
first from
qapi/block-core.json, which makes qapi/job.json's documentation go between qapi/block-core.json's subsection heading and contents.In the QEMU Storage Daemon QMP Reference Manual, section "Block Devices" contains nothing but an empty subsection "Block core (VM unrelated)". The latter's contents is at the end section "Socket data types", along with subsection "Block device exports". Subsection "Background jobs" is at the end of section "Cryptography". All this is because
storage-daemon/qapi/qapi-schema.jsonincludes modules in a confused order.Fix both as follows.
Turn subsection "Background jobs" into a section.
Move it before section "Block devices" in the QEMU QMP Reference Manual, by including
qapi/jobs.jsonright beforeqapi/block.json.Reorder include directives in
storage-daemon/qapi/qapi-schema.jsonto match the order inqapi/qapi-schema.json, so that the QEMU Storage Daemon QMP Reference Manual's section structure the QEMU QMP Reference Manual's.In the QEMU QMP Reference Manual, qapi/cryptodev.json's documentation is at the end of section "Virtio devices". That's because it lacks a section heading, and therefore gets squashed into whatever section happens to precede it.
Add section heading so it's in section "Cryptography devices".
Quoted 7 lines
Signed-off-by Markus Armbruster <[email protected]>--- qapi/cryptodev.json | 4 ++++ qapi/job.json | 2 +- qapi/qapi-schema.json | 2 +- storage-daemon/qapi/qapi-schema.json | 22 +++++++++++++++------- 4 files changed, 21 insertions(+), 9 deletions(-)
Signature · 3 lines
Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3266 Virtualization: qemu.org | libvirt.org
Re: [PATCH 16/16] qapi storage-daemon/qapi: Fix documentation section structure
Quoted 6 lines · Eric Blake
Quoted 3 lines · Markus Armbruster
In the QEMU QMP Reference Manual, subsection "Block core (VM unrelated)" is empty. Its contents is at the end of subsection "Background jobs" instead. That's because
qapi/job.jsonis includededincluded
Fixing...
Quoted 39 lines
Quoted 31 lines
first from
qapi/block-core.json, which makes qapi/job.json's documentation go between qapi/block-core.json's subsection heading and contents.In the QEMU Storage Daemon QMP Reference Manual, section "Block Devices" contains nothing but an empty subsection "Block core (VM unrelated)". The latter's contents is at the end section "Socket data types", along with subsection "Block device exports". Subsection "Background jobs" is at the end of section "Cryptography". All this is because
storage-daemon/qapi/qapi-schema.jsonincludes modules in a confused order.Fix both as follows.
Turn subsection "Background jobs" into a section.
Move it before section "Block devices" in the QEMU QMP Reference Manual, by including
qapi/jobs.jsonright beforeqapi/block.json.Reorder include directives in
storage-daemon/qapi/qapi-schema.jsonto match the order inqapi/qapi-schema.json, so that the QEMU Storage Daemon QMP Reference Manual's section structure the QEMU QMP Reference Manual's.In the QEMU QMP Reference Manual, qapi/cryptodev.json's documentation is at the end of section "Virtio devices". That's because it lacks a section heading, and therefore gets squashed into whatever section happens to precede it.
Add section heading so it's in section "Cryptography devices".
Quoted 7 lines
Signed-off-by Markus Armbruster <[email protected]>--- qapi/cryptodev.json | 4 ++++ qapi/job.json | 2 +- qapi/qapi-schema.json | 2 +- storage-daemon/qapi/qapi-schema.json | 22 +++++++++++++++------- 4 files changed, 21 insertions(+), 9 deletions(-)
Quoted 1 line
Reviewed-by Eric Blake <[email protected]>
Thanks!
Re: [PATCH 16/16] qapi storage-daemon/qapi: Fix documentation section structure
In reply to Markus ArmbrusterLooks good to me, thanks!
Quoted 125 lines · Markus Armbruster
In the QEMU QMP Reference Manual, subsection "Block core (VM unrelated)" is empty. Its contents is at the end of subsection "Background jobs" instead. That's because
qapi/job.jsonis includeded first fromqapi/block-core.json, which makes qapi/job.json's documentation go between qapi/block-core.json's subsection heading and contents.In the QEMU Storage Daemon QMP Reference Manual, section "Block Devices" contains nothing but an empty subsection "Block core (VM unrelated)". The latter's contents is at the end section "Socket data types", along with subsection "Block device exports". Subsection "Background jobs" is at the end of section "Cryptography". All this is because
storage-daemon/qapi/qapi-schema.jsonincludes modules in a confused order.Fix both as follows.
Turn subsection "Background jobs" into a section.
Move it before section "Block devices" in the QEMU QMP Reference Manual, by including
qapi/jobs.jsonright beforeqapi/block.json.Reorder include directives in
storage-daemon/qapi/qapi-schema.jsonto match the order inqapi/qapi-schema.json, so that the QEMU Storage Daemon QMP Reference Manual's section structure the QEMU QMP Reference Manual's.In the QEMU QMP Reference Manual, qapi/cryptodev.json's documentation is at the end of section "Virtio devices". That's because it lacks a section heading, and therefore gets squashed into whatever section happens to precede it.
Add section heading so it's in section "Cryptography devices".
Signed-off-by Markus Armbruster <[email protected]>--- qapi/cryptodev.json | 4 ++++ qapi/job.json | 2 +- qapi/qapi-schema.json | 2 +- storage-daemon/qapi/qapi-schema.json | 22 +++++++++++++++------- 4 files changed, 21 insertions(+), 9 deletions(-)qapi/cryptodev.json +4
-0@@ -4,6 +4,10 @@ # This work is licensed under the terms of the GNU GPL, version 2 or later. # See the COPYING file in the top-level directory. +## +# = Cryptography devices +## + ## # @QCryptodevBackendAlgType: #qapi/job.json +1
-1@@ -2,7 +2,7 @@ # vim: filetype=python ## -# == Background jobs +# = Background jobs ## ##qapi/qapi-schema.json +1
-1@@ -43,11 +43,11 @@ { 'include': 'sockets.json' } { 'include': 'run-state.json' } { 'include': 'crypto.json' } +{ 'include': 'job.json' } { 'include': 'block.json' } { 'include': 'block-export.json' } { 'include': 'char.json' } { 'include': 'dump.json' } -{ 'include': 'job.json' } { 'include': 'net.json' } { 'include': 'rdma.json' } { 'include': 'rocker.json' }storage-daemon/qapi/qapi-schema.json +15
-7@@ -15,18 +15,26 @@ { 'include': '../../qapi/pragma.json' } +# Documentation generated with qapi-gen.py is in source order, with +# included sub-schemas inserted at the first include directive +# (subsequent include directives have no effect). To get a sane and +# stable order, it's best to include each sub-schema just once, or +# include it first right here. + +{ 'include': '../../qapi/common.json' } +{ 'include': '../../qapi/sockets.json' } +{ 'include': '../../qapi/crypto.json' } +{ 'include': '../../qapi/job.json' } + ## # = Block devices ## { 'include': '../../qapi/block-core.json' } { 'include': '../../qapi/block-export.json' } + { 'include': '../../qapi/char.json' } -{ 'include': '../../qapi/common.json' } -{ 'include': '../../qapi/control.json' } -{ 'include': '../../qapi/crypto.json' } -{ 'include': '../../qapi/introspect.json' } -{ 'include': '../../qapi/job.json' } { 'include': '../../qapi/authz.json' } -{ 'include': '../../qapi/qom.json' } -{ 'include': '../../qapi/sockets.json' } { 'include': '../../qapi/transaction.json' } +{ 'include': '../../qapi/control.json' } +{ 'include': '../../qapi/introspect.json' } +{ 'include': '../../qapi/qom.json' }
Signature · 1 line
zhenwei pi
Quoted 5 lines · Markus Armbruster
It's always nice to get doc fixes into the release, but if it's too late, it's too late.
Generated code does not change, except for the last patch, which moves a bit of code without changing it.
I didn't deeply check the details, but looked through and nothing seems wrong to me. Good cleanup!
all patches:
PS: do you plan some automatic checks in build process to avoid similar style/naming problems in future?
Signature · 2 lines
Best regards, Vladimir
Quoted 11 lines · Vladimir Sementsov-Ogievskiy
Quoted 4 lines · Markus Armbruster
It's always nice to get doc fixes into the release, but if it's too late, it's too late.
Generated code does not change, except for the last patch, which moves a bit of code without changing it.I didn't deeply check the details, but looked through and nothing seems wrong to me. Good cleanup!
all patches:
Reviewed-by Vladimir Sementsov-Ogievskiy <[email protected]>
Thanks! (Belatedly)
Quoted 1 line
PS: do you plan some automatic checks in build process to avoid similar style/naming problems in future?
I'm about to post patches that make it somewhat harder to screw up indentation (PATCH 10 fixes such screwups). Harder, not impossible, because indentation is meaningful in rST.
I believe the best way to catch argument description screwups is making argument descriptions mandatory. I hope to find time for that.
Other than that, no promising ideas, I'm afraid.
Quoted 52 lines · Markus Armbruster
It's always nice to get doc fixes into the release, but if it's too late, it's too late.
Generated code does not change, except for the last patch, which moves a bit of code without changing it.
Markus Armbruster (16):
qga/qapi-schema: Tidy up documentation of guest-fsfreeze-status qga/qapi-schema: Fix a misspelled reference
qapi: Fix misspelled references
qapi: Fix up references to long gone error classes qapi/block-core: Clean up after removal of dirty bitmap @status
qapi: @foo should be used to reference, not ``foo``
qapi: Tidy up examples
qapi: Delete largely misleading "Stability Considerations"
qapi: Fix bullet list markup in documentation
qapi: Fix unintended definition lists in documentation qga/qapi-schema: Fix member documentation markup
qapi: Fix argument documentation markup
qapi: Replace ad hoc "since" documentation by member documentation
qapi: Fix misspelled section tags in doc comments
qapi: Format since information the conventional way: (since X.Y) qapi storage-daemon/qapi: Fix documentation section structuredocs/devel/qapi-code-gen.rst | 8 ++- docs/interop/firmware.json | 6 +- qapi/block-core.json | 82 ++++++++++++++-------------- qapi/block.json | 2 +- qapi/char.json | 4 +- qapi/control.json | 2 +- qapi/cryptodev.json | 4 ++ qapi/job.json | 4 +- qapi/machine-target.json | 2 +- qapi/machine.json | 26 +++++---- qapi/migration.json | 37 ++++++++----- qapi/misc.json | 6 +- qapi/net.json | 25 +++------ qapi/qapi-schema.json | 24 +------- qapi/qdev.json | 2 +- qapi/qom.json | 4 +- qapi/rdma.json | 2 +- qapi/replay.json | 3 + qapi/run-state.json | 6 +- qapi/stats.json | 3 +- qapi/tpm.json | 3 +- qapi/trace.json | 1 + qapi/ui.json | 12 ++-- qga/qapi-schema.json | 10 ++-- storage-daemon/qapi/qapi-schema.json | 22 +++++--- 25 files changed, 154 insertions(+), 146 deletions(-)
Quoted 4 lines
--
2.39.2
lgtm,
Signature · 1 line
Marc-André Lureau