diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index ea8228518c..76be722f4c 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -737,9 +737,8 @@ Types, commands, and events share a common namespace. Therefore, generally speaking, type definitions should always use CamelCase for user-defined type names, while built-in types are lowercase. -Type names ending with ``Kind`` or ``List`` are reserved for the -generator, which uses them for implicit union enums and array types, -respectively. +Type names ending with ``List`` are reserved for the generator, which +uses them for array types. Command names, member names within a type, and feature names should be all lower case with words separated by a hyphen. However, some @@ -990,8 +989,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:: diff --git a/docs/devel/writing-monitor-commands.rst b/docs/devel/writing-monitor-commands.rst index 2c11e71665..b6ee4fa063 100644 --- a/docs/devel/writing-monitor-commands.rst +++ b/docs/devel/writing-monitor-commands.rst @@ -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. +: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 implemented on top of QMP. The typical HMP command wraps around an diff --git a/docs/interop/bitmaps.rst b/docs/interop/bitmaps.rst index 1de46febdc..ddf8947d54 100644 --- a/docs/interop/bitmaps.rst +++ b/docs/interop/bitmaps.rst @@ -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 `_ for a full reference of all -QMP commands. +interface. If you are not familiar, see the :doc:`qmp-spec` for the +protocol, and :doc:`qemu-qmp-ref` for a full reference of all QMP +commands. Supported Commands ~~~~~~~~~~~~~~~~~~ diff --git a/include/qapi/visitor.h b/include/qapi/visitor.h index d53a84c9ba..27b85d4700 100644 --- a/include/qapi/visitor.h +++ b/include/qapi/visitor.h @@ -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: diff --git a/include/qemu/yank.h b/include/qemu/yank.h index 1907150933..3d88af6996 100644 --- a/include/qemu/yank.h +++ b/include/qemu/yank.h @@ -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. diff --git a/qapi/block-core.json b/qapi/block-core.json index ca390c5700..3919156d49 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -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' }, diff --git a/qapi/char.json b/qapi/char.json index c1bab7b855..6c6ad3b10c 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -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 ## diff --git a/qapi/introspect.json b/qapi/introspect.json index 9173e60fdd..8df1ce85ed 100644 --- a/qapi/introspect.json +++ b/qapi/introspect.json @@ -261,7 +261,7 @@ # # @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. +# :doc:`/devel/qapi-code-gen` section Alternate types. # # On the wire, this can be any of the members. # diff --git a/qapi/machine.json b/qapi/machine.json index b6d634b30d..aa99fa333f 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -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 # diff --git a/qapi/migration.json b/qapi/migration.json index eb2f883513..489b591c23 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -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', diff --git a/qapi/misc-target.json b/qapi/misc-target.json index 88291453ba..9195e7d26b 100644 --- a/qapi/misc-target.json +++ b/qapi/misc-target.json @@ -475,7 +475,7 @@ # @port: The port number # # Returns: -# - Nothing on success. +# - Nothing on success. # # Since: 8.0 # diff --git a/qapi/misc.json b/qapi/misc.json index 3622d98d01..2ca8c39874 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -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 # diff --git a/qapi/net.json b/qapi/net.json index 8095b68fa8..68493d6ac9 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -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 # diff --git a/qapi/qapi-util.c b/qapi/qapi-util.c index 63596e11c5..65a7d18437 100644 --- a/qapi/qapi-util.c +++ b/qapi/qapi-util.c @@ -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. diff --git a/qapi/qdev.json b/qapi/qdev.json index 6bc5a733b8..25bac5e611 100644 --- a/qapi/qdev.json +++ b/qapi/qdev.json @@ -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 diff --git a/qapi/qom.json b/qapi/qom.json index 95516ba325..84af23fe24 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -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 # diff --git a/qapi/yank.json b/qapi/yank.json index 87ec7cab96..60eda20816 100644 --- a/qapi/yank.json +++ b/qapi/yank.json @@ -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: # diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index bf31018aef..48cd55a38c 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -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. diff --git a/util/yank.c b/util/yank.c index abf47c346d..eaac50539c 100644 --- a/util/yank.c +++ b/util/yank.c @@ -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;