qapi qmp: Documentation fixes
cover qapi qmp: Documentation fixes
Markus Armbruster (7):
docs/devel/qapi-code-gen: Fix missing ':' in tagged section docs
docs: Replace dangling references to docs/interop/qmp-intro.txt
qapi: Fix dangling references to docs/devel/qapi-code-gen.txt docs/interop/bitmaps: Clean up a reference to qemu-qmp-ref
qapi: Fix mangled "Returns" sections in documentation
qapi: Indent tagged doc comment sections properly
qapi: Fix malformed "Since:" section tags (again)
docs/devel/qapi-code-gen.rst | 4 ++-- docs/devel/writing-monitor-commands.rst | 4 ++-- docs/interop/bitmaps.rst | 6 +++--- qapi/block-core.json | 4 ++-- qapi/char.json | 4 ++-- qapi/introspect.json | 2 +- qapi/machine.json | 24 ++++++++++++------------ qapi/migration.json | 14 +++++++------- qapi/misc-target.json | 2 +- qapi/misc.json | 10 +++++----- qapi/net.json | 15 +++++++++------ qapi/qdev.json | 5 +++-- qapi/qom.json | 10 ++++++---- qapi/yank.json | 4 ++-- include/qapi/visitor.h | 2 +- include/qemu/yank.h | 2 +- qapi/qapi-util.c | 2 +- util/yank.c | 2 +- scripts/qapi/parser.py | 2 +- 19 files changed, 62 insertions(+), 56 deletions(-)
Signature · 1 line
2.43.0
PATCH 1/7 docs/devel/qapi-code-gen: Fix missing ':' in tagged section docs
--- docs/devel/qapi-code-gen.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
docs/devel/qapi-code-gen.rst +2 -2
@@ -990,8 +990,8 @@ this:: # @feature: Description text A tagged section starts with one of the following words: -"Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:". -The section ends with the start of a new section. +"Note:"/"Notes:", "Since:", "Example:"/"Examples:", "Returns:", +"TODO:". The section ends with the start of a new section. The second and subsequent lines of sections other than "Example"/"Examples" should be indented like this::
Signature · 1 line
2.43.0
PATCH 2/7 docs: Replace dangling references to docs/interop/qmp-intro.txt
In reply to Markus ArmbrusterDeletion of docs/interop/qmp-intro.txt left two dangling references behind. Replace them by references to docs/interop/qmp-spec.rst.
--- docs/devel/writing-monitor-commands.rst | 4 ++-- docs/interop/bitmaps.rst | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-)
docs/devel/writing-monitor-commands.rst +2 -2
@@ -8,8 +8,8 @@ This document doesn't discuss QMP protocol level details, nor does it dive into the QAPI framework implementation. For an in-depth introduction to the QAPI framework, please refer to -docs/devel/qapi-code-gen.txt. For documentation about the QMP protocol, -start with docs/interop/qmp-intro.txt. +docs/devel/qapi-code-gen.txt. For the QMP protocol, see the +:doc:`/interop/qmp-spec`. New commands may be implemented in QMP only. New HMP commands should be implemented on top of QMP. The typical HMP command wraps around an
docs/interop/bitmaps.rst +3 -3
@@ -166,9 +166,9 @@ Basic QMP Usage --------------- The primary interface to manipulating bitmap objects is via the QMP -interface. If you are not familiar, see docs/interop/qmp-intro.txt for a broad -overview, and `qemu-qmp-ref <qemu-qmp-ref.html>`_ for a full reference of all -QMP commands. +interface. If you are not familiar, see the :doc:`qmp-spec` for the +protocol, and `qemu-qmp-ref <qemu-qmp-ref.html>`_ for a full +reference of all QMP commands. Supported Commands ~~~~~~~~~~~~~~~~~~
Signature · 1 line
2.43.0
PATCH 3/7 qapi: Fix dangling references to docs/devel/qapi-code-gen.txt
In reply to Markus ArmbrusterConversion of docs/devel/qapi-code-gen.txt to ReST left several dangling references behind. Fix them to point to docs/devel/qapi-code-gen.rst.
--- docs/devel/writing-monitor-commands.rst | 2 +- qapi/introspect.json | 4 ++-- include/qapi/visitor.h | 2 +- include/qemu/yank.h | 2 +- qapi/qapi-util.c | 2 +- util/yank.c | 2 +- scripts/qapi/parser.py | 2 +- 7 files changed, 8 insertions(+), 8 deletions(-)
docs/devel/writing-monitor-commands.rst +1 -1
@@ -8,7 +8,7 @@ This document doesn't discuss QMP protocol level details, nor does it dive into the QAPI framework implementation. For an in-depth introduction to the QAPI framework, please refer to -docs/devel/qapi-code-gen.txt. For the QMP protocol, see the +:doc:`qapi-code-gen`. For the QMP protocol, see the :doc:`/interop/qmp-spec`. New commands may be implemented in QMP only. New HMP commands should be
qapi/introspect.json +2 -2
@@ -260,8 +260,8 @@ # Additional SchemaInfo members for meta-type 'alternate'. # # @members: the alternate type's members, in no particular order. The -# members' wire encoding is distinct, see -# docs/devel/qapi-code-gen.txt section Alternate types. +# members' wire encoding is distinct, see :doc:`qapi-code-gen` +# section Alternate types. # # On the wire, this can be any of the members. #
include/qapi/visitor.h +1 -1
@@ -39,7 +39,7 @@* limitations; see the documentation for each visitor for more * details on what it supports. Also, see visitor-impl.h for the * callback contracts implemented by each visitor, and -* docs/devel/qapi-code-gen.txt for more about the QAPI code +* docs/devel/qapi-code-gen.rst for more about the QAPI code * generator. * * All of the visitors are created via:
include/qemu/yank.h +1 -1
@@ -45,7 +45,7 @@ void yank_unregister_instance(const YankInstance *instance);* yank_register_function: Register a yank function * * This registers a yank function. All limitations of qmp oob commands apply -* to the yank function as well. See docs/devel/qapi-code-gen.txt under +* to the yank function as well. See docs/devel/qapi-code-gen.rst under * "An OOB-capable command handler must satisfy the following conditions". * * This function is thread-safe.
qapi/qapi-util.c +1 -1
@@ -112,7 +112,7 @@ bool qapi_bool_parse(const char *name, const char *value, bool *obj, Error **err* It may be prefixed by __RFQDN_ (downstream extension), where RFQDN * may contain only letters, digits, hyphen and period. * The special exception for enumeration names is not implemented. -* See docs/devel/qapi-code-gen.txt for more on QAPI naming rules. +* See docs/devel/qapi-code-gen.rst for more on QAPI naming rules. * Keep this consistent with scripts/qapi-gen.py! * If @complete, the parse fails unless it consumes @str completely. * Return its length on success, -1 on failure.
util/yank.c +1 -1
@@ -35,7 +35,7 @@ typedef struct YankInstanceEntry YankInstanceEntry;/* * This lock protects the yank_instance_list below. Because it's taken by * OOB-capable commands, it must be "fast", i.e. it may only be held for a -* bounded, short time. See docs/devel/qapi-code-gen.txt for additional +* bounded, short time. See docs/devel/qapi-code-gen.rst for additional * information. */ static QemuMutex yank_lock;
scripts/qapi/parser.py +1 -1
@@ -71,7 +71,7 @@ class QAPISchemaParser: Parse QAPI schema source. Parse a JSON-esque schema file and process directives. See - qapi-code-gen.txt section "Schema Syntax" for the exact syntax. + qapi-code-gen.rst section "Schema Syntax" for the exact syntax. Grammatical validation is handled later by `expr.check_exprs()`. :param fname: Source file name.
Signature · 1 line
2.43.0
PATCH 4/7 docs/interop/bitmaps: Clean up a reference to qemu-qmp-ref
In reply to Markus Armbrusterdocs/interop/bitmaps.rst uses references like
`qemu-qmp-ref <qemu-qmp-ref.html>`_
`query-block <qemu-qmp-ref.html#index-query_002dblock>`_to refer to and into docs/interop/qemu-qmp-ref.rst.
Clean up the former: use :doc:qemu-qmp-ref.
I don't know how to clean up the latter.
--- docs/interop/bitmaps.rst | 4 ++-- qapi/introspect.json | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-)
docs/interop/bitmaps.rst +2 -2
@@ -167,8 +167,8 @@ Basic QMP Usage The primary interface to manipulating bitmap objects is via the QMP interface. If you are not familiar, see the :doc:`qmp-spec` for the -protocol, and `qemu-qmp-ref <qemu-qmp-ref.html>`_ for a full -reference of all QMP commands. +protocol, and :doc:`qemu-qmp-ref` for a full reference of all QMP +commands. Supported Commands ~~~~~~~~~~~~~~~~~~
qapi/introspect.json +2 -2
@@ -260,8 +260,8 @@ # Additional SchemaInfo members for meta-type 'alternate'. # # @members: the alternate type's members, in no particular order. The -# members' wire encoding is distinct, see :doc:`qapi-code-gen` -# section Alternate types. +# members' wire encoding is distinct, see +# :doc:`/devel/qapi-code-gen` section Alternate types. # # On the wire, this can be any of the members. #
Signature · 1 line
2.43.0
Re: [PATCH 4/7] docs/interop/bitmaps: Clean up a reference to qemu-qmp-ref
Quoted 11 lines · Markus Armbruster
docs/interop/bitmaps.rstuses references like`qemu-qmp-ref <qemu-qmp-ref.html>`_ `query-block <qemu-qmp-ref.html#index-query_002dblock>`_to refer to and into
docs/interop/qemu-qmp-ref.rst.Clean up the former: use :doc:
qemu-qmp-ref.I don't know how to clean up the latter.
It used to have anchors that seemed to have semi-stable names, but I guess that's not really true anymore.
Now it's just stuff like qapidoc-423. Well, neat...
No, I think this requires the Real Fix :tm: now...
Quoted 40 lines
Signed-off-by Markus Armbruster <[email protected]>--- docs/interop/bitmaps.rst | 4 ++-- qapi/introspect.json | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-)docs/interop/bitmaps.rst +2
-2@@ -167,8 +167,8 @@ Basic QMP Usage The primary interface to manipulating bitmap objects is via the QMP interface. If you are not familiar, see the :doc:`qmp-spec` for the -protocol, and `qemu-qmp-ref <qemu-qmp-ref.html>`_ for a full -reference of all QMP commands. +protocol, and :doc:`qemu-qmp-ref` for a full reference of all QMP +commands. Supported Commands ~~~~~~~~~~~~~~~~~~qapi/introspect.json +2
-3@@ -260,8 +260,8 @@ # Additional SchemaInfo members for meta-type 'alternate'. # # @members: the alternate type's members, in no particular order. The -# members' wire encoding is distinct, see :doc:`qapi-code-gen` -# section Alternate types. +# members' wire encoding is distinct, see +# :doc:`/devel/qapi-code-gen` section Alternate types. # # On the wire, this can be any of the members. # --2.43.0
Re: [PATCH 4/7] docs/interop/bitmaps: Clean up a reference to qemu-qmp-ref
Quoted 53 lines · John Snow
Quoted 11 lines · Markus Armbruster
docs/interop/bitmaps.rstuses references like`qemu-qmp-ref <qemu-qmp-ref.html>`_ `query-block <qemu-qmp-ref.html#index-query_002dblock>`_to refer to and into
docs/interop/qemu-qmp-ref.rst.Clean up the former: use :doc:
qemu-qmp-ref.I don't know how to clean up the latter.
It used to have anchors that seemed to have semi-stable names, but I guess that's not really true anymore.
Now it's just stuff like
qapidoc-423. Well, neat...No, I think this requires the Real Fix :tm: now...
Quoted 32 lines
Signed-off-by Markus Armbruster <[email protected]>--- docs/interop/bitmaps.rst | 4 ++-- qapi/introspect.json | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-)docs/interop/bitmaps.rst +2
-2@@ -167,8 +167,8 @@ Basic QMP Usage The primary interface to manipulating bitmap objects is via the QMP interface. If you are not familiar, see the :doc:`qmp-spec` for the -protocol, and `qemu-qmp-ref <qemu-qmp-ref.html>`_ for a full -reference of all QMP commands. +protocol, and :doc:`qemu-qmp-ref` for a full reference of all QMP +commands. Supported Commands ~~~~~~~~~~~~~~~~~~qapi/introspect.json +0
-2@@ -260,8 +260,8 @@ # Additional SchemaInfo members for meta-type 'alternate'. # # @members: the alternate type's members, in no particular order. The -# members' wire encoding is distinct, see :doc:`qapi-code-gen` -# section Alternate types.
Quoted 8 lines
Quoted 8 lines
qapi/introspect.json +2
-1+# members' wire encoding is distinct, see +# :doc:`/devel/qapi-code-gen` section Alternate types. # # On the wire, this can be any of the members. # --2.43.0
fyi/to whom it may concern:
"what cross-reference points are defined in our documentation?"
Quoted 2 lines
wget https://www.qemu.org/docs/master/objects.inv
python -m sphinx.ext.intersphinx objects.inv | less
nose around to your heart's content.
--js
PATCH 5/7 qapi: Fix mangled "Returns" sections in documentation
In reply to Markus ArmbrusterCommit e050e426782e (qapi: Use explicit bulleted lists) added list markup to correct bad rendering:
A JSON block comment like this:
Returns: nothing on success
If @node is not a valid block device, DeviceNotFound If @name is not found, GenericError with an explanation
renders like this:
Returns: nothing on success If node is not a valid block device, DeviceNotFound If name is not found, GenericError with an explanation
because whitespace is not significant.
Use an actual bulleted list, so that the formatting is correct.
It missed a few instances. Commit a937b6aa739 (qapi: Reformat doc comments to conform to current conventions) then reflowed them.
Revert the reflowing, and add list markup.
--- qapi/net.json | 15 +++++++++------ qapi/qdev.json | 5 +++-- qapi/qom.json | 10 ++++++---- 3 files changed, 18 insertions(+), 12 deletions(-)
qapi/net.json +9 -6
@@ -18,8 +18,9 @@ # # @up: true to set the link status to be up # -# Returns: Nothing on success If @name is not a valid network device, -# DeviceNotFound +# Returns: +# - Nothing on success +# - If @name is not a valid network device, DeviceNotFound # # Since: 0.14 #
@@ -44,8 +45,9 @@ # # Since: 0.14 # -# Returns: Nothing on success If @type is not a valid network backend, -# DeviceNotFound +# Returns: +# - Nothing on success +# - If @type is not a valid network backend, DeviceNotFound # # Example: #
@@ -64,8 +66,9 @@ # # @id: the name of the network backend to remove # -# Returns: Nothing on success If @id is not a valid network backend, -# DeviceNotFound +# Returns: +# - Nothing on success +# - If @id is not a valid network backend, DeviceNotFound # # Since: 0.14 #
qapi/qdev.json +3 -2
@@ -89,8 +89,9 @@ # # @id: the device's ID or QOM path # -# Returns: Nothing on success If @id is not a valid device, -# DeviceNotFound +# Returns: +# - Nothing on success +# - If @id is not a valid device, DeviceNotFound # # Notes: When this command completes, the device may not be removed # from the guest. Hot removal is an operation that requires guest
qapi/qom.json +6 -4
@@ -1056,8 +1056,9 @@ # # Create a QOM object. # -# Returns: Nothing on success Error if @qom-type is not a valid class -# name +# Returns: +# - Nothing on success +# - Error if @qom-type is not a valid class name # # Since: 2.0 #
@@ -1078,8 +1079,9 @@ # # @id: the name of the QOM object to remove # -# Returns: Nothing on success Error if @id is not a valid id for a QOM -# object +# Returns: +# - Nothing on success +# - Error if @id is not a valid id for a QOM object # # Since: 2.0 #
Signature · 1 line
2.43.0
PATCH 6/7 qapi: Indent tagged doc comment sections properly
In reply to Markus Armbrusterdocs/devel/qapi-code-gen demands that the "second and subsequent lines of sections other than "Example"/"Examples" should be indented". Commit a937b6aa739 (qapi: Reformat doc comments to conform to current conventions) missed a few instances, and a few more have crept in since. Indent them.
--- qapi/char.json | 4 ++-- qapi/machine.json | 24 ++++++++++++------------ qapi/misc-target.json | 2 +- qapi/misc.json | 10 +++++----- qapi/yank.json | 4 ++-- 5 files changed, 22 insertions(+), 22 deletions(-)
qapi/char.json +2 -2
@@ -391,8 +391,8 @@ # @rows: console height, in chars # # Note: the options are only effective when the VNC or SDL graphical -# display backend is active. They are ignored with the GTK, Spice, VNC -# and D-Bus display backends. +# display backend is active. They are ignored with the GTK, +# Spice, VNC and D-Bus display backends. # # Since: 1.5 ##
qapi/machine.json +12 -12
@@ -1059,10 +1059,10 @@ # From it we have: balloon_size = vm_ram_size - @value # # Returns: -# - Nothing on success -# - If the balloon driver is enabled but not functional because the -# KVM kernel module cannot support it, KVMMissingCap -# - If no balloon device is present, DeviceNotActive +# - Nothing on success +# - If the balloon driver is enabled but not functional because +# the KVM 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, the balloon size may not have changed. A guest can
@@ -1097,10 +1097,10 @@ # Return information about the balloon device. # # Returns: -# - @BalloonInfo on success -# - If the balloon driver is enabled but not functional because the -# KVM kernel module cannot support it, KVMMissingCap -# - If no balloon device is present, DeviceNotActive +# - @BalloonInfo on success +# - If the balloon driver is enabled but not functional because +# the KVM kernel module cannot support it, KVMMissingCap +# - If no balloon device is present, DeviceNotActive # # Since: 0.14 #
@@ -1161,10 +1161,10 @@ # message from the guest. # # Returns: -# - @HvBalloonInfo on success -# - If no hv-balloon device is present, guest memory status reporting -# is not enabled or no guest memory status report received yet, -# GenericError +# - @HvBalloonInfo on success +# - If no hv-balloon device is present, guest memory status +# reporting is not enabled or no guest memory status report +# received yet, GenericError # # Since: 8.2 #
qapi/misc-target.json +1 -1
@@ -475,7 +475,7 @@ # @port: The port number # # Returns: -# - Nothing on success. +# - Nothing on success. # # Since: 8.0 #
qapi/misc.json +5 -5
@@ -344,9 +344,9 @@ # @opaque: A free-form string that can be used to describe the fd. # # Returns: -# - @AddfdInfo on success -# - If file descriptor was not received, GenericError -# - If @fdset-id is a negative value, GenericError +# - @AddfdInfo on success +# - 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. #
@@ -374,8 +374,8 @@ # @fd: The file descriptor that is to be removed. # # Returns: -# - Nothing on success -# - If @fdset-id or @fd is not found, GenericError +# - Nothing on success +# - If @fdset-id or @fd is not found, GenericError # # Since: 1.2 #
qapi/yank.json +2 -2
@@ -77,8 +77,8 @@ # Takes a list of @YankInstance as argument. # # Returns: -# - Nothing on success -# - @DeviceNotFound error, if any of the YankInstances doesn't exist +# - Nothing on success +# - @DeviceNotFound error, if any of the YankInstances doesn't exist # # Example: #
Signature · 1 line
2.43.0
PATCH 7/7 qapi: Fix malformed "Since:" section tags (again)
In reply to Markus Armbruster"Since X.Y" is not recognized as a tagged section, and therefore not formatted as such in generated documentation. Fix by adding the required colon.
Previously fixed in commit 433a4fdc420 (qapi: Fix malformed "Since:" section tags)
--- qapi/block-core.json | 4 ++-- qapi/migration.json | 14 +++++++------- 2 files changed, 9 insertions(+), 9 deletions(-)
qapi/block-core.json +2 -2
@@ -1361,7 +1361,7 @@ # target, i.e. same data and new writes are done synchronously to # both. # -# Since 8.2 +# Since: 8.2 ## { 'struct': 'BlockJobInfoMirror', 'data': { 'actively-synced': 'bool' } }
@@ -3080,7 +3080,7 @@ # # @type: The job type # -# Since 8.2 +# Since: 8.2 ## { 'union': 'BlockJobChangeOptions', 'base': { 'id': 'str', 'type': 'JobType' },
qapi/migration.json +7 -7
@@ -1597,7 +1597,7 @@ # # @file: Direct the migration stream to a file. # -# Since 8.2 +# Since: 8.2 ## { 'enum': 'MigrationAddressType', 'data': [ 'socket', 'exec', 'rdma', 'file' ] }
@@ -1609,7 +1609,7 @@ # # @offset: The file offset where the migration stream will start # -# Since 8.2 +# Since: 8.2 ## { 'struct': 'FileMigrationArgs', 'data': { 'filename': 'str',
@@ -1620,7 +1620,7 @@ # # @args: command (list head) and arguments to execute. # -# Since 8.2 +# Since: 8.2 ## { 'struct': 'MigrationExecCommand', 'data': {'args': [ 'str' ] } }
@@ -1630,7 +1630,7 @@ # # Migration endpoint configuration. # -# Since 8.2 +# Since: 8.2 ## { 'union': 'MigrationAddress', 'base': { 'transport' : 'MigrationAddressType'},
@@ -1648,7 +1648,7 @@ # # @main: Main outbound migration channel. # -# Since 8.1 +# Since: 8.1 ## { 'enum': 'MigrationChannelType', 'data': [ 'main' ] }
@@ -1662,7 +1662,7 @@ # # @addr: Migration endpoint configuration on destination interface. # -# Since 8.1 +# Since: 8.1 ## { 'struct': 'MigrationChannel', 'data': {
@@ -2126,7 +2126,7 @@ # # @millisecond: value is in milliseconds # -# Since 8.2 +# Since: 8.2 # ## { 'enum': 'TimeUnit',
Signature · 1 line
2.43.0
Re: [PATCH 7/7] qapi: Fix malformed "Since:" section tags (again)
Quoted 4 lines · Markus Armbruster
"Since X.Y" is not recognized as a tagged section, and therefore not formatted as such in generated documentation. Fix by adding the required colon.
Quoted 8 lines
Previously fixed in commit
433a4fdc420(qapi: Fix malformed "Since:" section tags)Signed-off-by Markus Armbruster <[email protected]>--- qapi/block-core.json | 4 ++-- qapi/migration.json | 14 +++++++------- 2 files changed, 9 insertions(+), 9 deletions(-)
Quoted 8 lines · Markus Armbruster
Markus Armbruster (7):
docs/devel/qapi-code-gen: Fix missing ':' in tagged section docs
docs: Replace dangling references todocs/interop/qmp-intro.txt
qapi: Fix dangling references todocs/devel/qapi-code-gen.txtdocs/interop/bitmaps: Clean up a reference to qemu-qmp-ref
qapi: Fix mangled "Returns" sections in documentation
qapi: Indent tagged doc comment sections properly
qapi: Fix malformed "Since:" section tags (again)
For the series:
Signature · 3 lines
Eric Blake, Principal Software Engineer Red Hat, Inc. Virtualization: qemu.org | libguestfs.org
Queued.