From 13b86cbd2cbd12397143106bf8a93486397c4b9e Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Tue, 26 Oct 2021 13:10:22 +0200 Subject: [PATCH 1/3] docs/devel/qapi-code-gen: Drop a duplicate paragraph Commit 55ec69f8b1 "docs/devel/qapi-code-gen.txt: Update to new rST backend conventions" accidentally duplicated a paragraph. Drop it. Cc: Peter Maydell Signed-off-by: Markus Armbruster Message-Id: <20211026111023.76937-2-armbru@redhat.com> Reviewed-by: John Snow --- docs/devel/qapi-code-gen.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 38f2d7aad3..b5761f60cd 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -1000,12 +1000,6 @@ multiline argument descriptions. A 'Since: x.y.z' tagged section lists the release that introduced the definition. -The text of a section can start on a new line, in -which case it must not be indented at all. It can also start -on the same line as the 'Note:', 'Returns:', etc tag. In this -case if it spans multiple lines then second and subsequent -lines must be indented to match the first. - An 'Example' or 'Examples' section is automatically rendered entirely as literal fixed-width text. In other sections, the text is formatted, and rST markup can be used. From 53e9e547d20e91414e899034cf43720a8bf197be Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Tue, 26 Oct 2021 13:10:23 +0200 Subject: [PATCH 2/3] docs/devel/qapi-code-gen: Belatedly document feature documentation Commit 6a8c0b5102 "qapi: Add feature flags to struct types" neglected to document how to document feature flags. Make up for that. Cc: Kevin Wolf Signed-off-by: Markus Armbruster Message-Id: <20211026111023.76937-3-armbru@redhat.com> [Editing accident fixed] --- docs/devel/qapi-code-gen.rst | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index b5761f60cd..a3b5473089 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -956,15 +956,16 @@ definition must have documentation. Definition documentation starts with a line naming the definition, followed by an optional overview, a description of each argument (for commands and events), member (for structs and unions), branch (for -alternates), or value (for enums), and finally optional tagged -sections. +alternates), or value (for enums), a description of each feature (if +any), and finally optional tagged sections. -Descriptions of arguments can span multiple lines. The description -text can start on the line following the '\@argname:', in which case it -must not be indented at all. It can also start on the same line as -the '\@argname:'. In this case if it spans multiple lines then second -and subsequent lines must be indented to line up with the first -character of the first line of the description:: +The description of an argument or feature 'name' starts with +'\@name:'. The description text can start on the line following the +'\@name:', in which case it must not be indented at all. It can also +start on the same line as the '\@name:'. In this case if it spans +multiple lines then second and subsequent lines must be indented to +line up with the first character of the first line of the +description:: # @argone: # This is a two line description @@ -986,6 +987,12 @@ The number of spaces between the ':' and the text is not significant. Extensions added after the definition was first released carry a '(since x.y.z)' comment. +The feature descriptions must be preceded by a line "Features:", like +this:: + + # Features: + # @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. From 8c0bae5a19478db93371570b57164c63392a2d50 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Tue, 9 Nov 2021 15:55:59 +0100 Subject: [PATCH 3/3] qapi: Belatedly mark unstable QMP parts with feature 'unstable' MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The work in merge commit e86e00a2493 lacks special feature flag 'unstable', because it raced with it. Add it where it's missing. Signed-off-by: Markus Armbruster Message-Id: <20211109145559.2122827-1-armbru@redhat.com> Reviewed-by: Damien Hedde Reviewed-by: Daniel P. Berrangé Reviewed-by: Philippe Mathieu-Daudé --- qapi/machine.json | 54 +++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 45 insertions(+), 9 deletions(-) diff --git a/qapi/machine.json b/qapi/machine.json index 17794ef681..067e3f5378 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -1417,107 +1417,143 @@ # # Query interrupt statistics # +# Features: +# @unstable: This command is meant for debugging. +# # Returns: interrupt statistics # # Since: 6.2 ## { 'command': 'x-query-irq', - 'returns': 'HumanReadableText' } + 'returns': 'HumanReadableText', + 'features': [ 'unstable' ] } ## # @x-query-jit: # # Query TCG compiler statistics # +# Features: +# @unstable: This command is meant for debugging. +# # Returns: TCG compiler statistics # # Since: 6.2 ## { 'command': 'x-query-jit', 'returns': 'HumanReadableText', - 'if': 'CONFIG_TCG' } + 'if': 'CONFIG_TCG', + 'features': [ 'unstable' ] } ## # @x-query-numa: # # Query NUMA topology information # +# Features: +# @unstable: This command is meant for debugging. +# # Returns: topology information # # Since: 6.2 ## { 'command': 'x-query-numa', - 'returns': 'HumanReadableText' } + 'returns': 'HumanReadableText', + 'features': [ 'unstable' ] } ## # @x-query-opcount: # # Query TCG opcode counters # +# Features: +# @unstable: This command is meant for debugging. +# # Returns: TCG opcode counters # # Since: 6.2 ## { 'command': 'x-query-opcount', 'returns': 'HumanReadableText', - 'if': 'CONFIG_TCG' } + 'if': 'CONFIG_TCG', + 'features': [ 'unstable' ] } ## # @x-query-profile: # # Query TCG profiling information # +# Features: +# @unstable: This command is meant for debugging. +# # Returns: profile information # # Since: 6.2 ## { 'command': 'x-query-profile', - 'returns': 'HumanReadableText' } + 'returns': 'HumanReadableText', + 'features': [ 'unstable' ] } ## # @x-query-ramblock: # # Query system ramblock information # +# Features: +# @unstable: This command is meant for debugging. +# # Returns: system ramblock information # # Since: 6.2 ## { 'command': 'x-query-ramblock', - 'returns': 'HumanReadableText' } + 'returns': 'HumanReadableText', + 'features': [ 'unstable' ] } ## # @x-query-rdma: # # Query RDMA state # +# Features: +# @unstable: This command is meant for debugging. +# # Returns: RDMA state # # Since: 6.2 ## { 'command': 'x-query-rdma', - 'returns': 'HumanReadableText' } + 'returns': 'HumanReadableText', + 'features': [ 'unstable' ] } ## # @x-query-roms: # # Query information on the registered ROMS # +# Features: +# @unstable: This command is meant for debugging. +# # Returns: registered ROMs # # Since: 6.2 ## { 'command': 'x-query-roms', - 'returns': 'HumanReadableText' } + 'returns': 'HumanReadableText', + 'features': [ 'unstable' ] } ## # @x-query-usb: # # Query information on the USB devices # +# Features: +# @unstable: This command is meant for debugging. +# # Returns: USB device information # # Since: 6.2 ## { 'command': 'x-query-usb', - 'returns': 'HumanReadableText' } + 'returns': 'HumanReadableText', + 'features': [ 'unstable' ] }