mirror of
https://github.com/Motorhead1991/qemu.git
synced 2025-08-07 01:33:56 -06:00
QAPI patches patches for 2023-05-09
-----BEGIN PGP SIGNATURE----- iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmRbUEYSHGFybWJydUBy ZWRoYXQuY29tAAoJEDhwtADrkYZTmzEP/3pDpVxpP7xXLevl2vFqkFyHEjc0L3N4 x//ljgQojAdM6WU3e0qqOfp/NE2ktUg5D3z+QNiVP1/xXv/dtMGATdG+X9AZs0US XnhdicYdBng8bGuhlNuNY8QJ/I4ALwUR44LVOYibVohv2RVYWBapGiHowpyTyABq sFSHrj/cgvTMUn53yp7veZTo6rWG6RU/D5uUTOMsvKeAoHoOXMyBxV01SCt84t/J pcelINcriP6cQVzgfm1B39UNa0IxinGxEx/IIaxz5Ju66G05HTs4CsBFAF6/0QI/ 3YerGWPt9fF6+qYNn21Gg9CL1fHHppNqTXkcuTeGn/Ohg53bosktti5Ysn73vtpR GWsJr6M4KQ1SwEbZIiFZCS3A4VTbRcr7WkXets39pcpxGDlNisi+zfV95kNo09xR hxi8SuWgb2OfQpVs/71eunp+PM1ZQsODurcy4x0/rlYJfhk53kQSMRtlfy5Cn6uY +weWUgygBSWG/w0qanWWK5TF1DNlRKzbix6cmMuGGKcpyF7EMWE1kqmjmmu7CQvM a3aPTqGtUt0LeqBQIhmeq/jEwd3vxQa1R85gd0/0sWxEMHkPXVfVoaryiaWAykye 7r+c8o/41c44zs8YxdZrz72su9fqKC/TeVf5soU46ZucmH8D6f7QHy+s1ec2PEjY l6cRIXTXHeQe =j6cJ -----END PGP SIGNATURE----- Merge tag 'pull-qapi-2023-05-09-v2' of https://repo.or.cz/qemu/armbru into staging QAPI patches patches for 2023-05-09 # -----BEGIN PGP SIGNATURE----- # # iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmRbUEYSHGFybWJydUBy # ZWRoYXQuY29tAAoJEDhwtADrkYZTmzEP/3pDpVxpP7xXLevl2vFqkFyHEjc0L3N4 # x//ljgQojAdM6WU3e0qqOfp/NE2ktUg5D3z+QNiVP1/xXv/dtMGATdG+X9AZs0US # XnhdicYdBng8bGuhlNuNY8QJ/I4ALwUR44LVOYibVohv2RVYWBapGiHowpyTyABq # sFSHrj/cgvTMUn53yp7veZTo6rWG6RU/D5uUTOMsvKeAoHoOXMyBxV01SCt84t/J # pcelINcriP6cQVzgfm1B39UNa0IxinGxEx/IIaxz5Ju66G05HTs4CsBFAF6/0QI/ # 3YerGWPt9fF6+qYNn21Gg9CL1fHHppNqTXkcuTeGn/Ohg53bosktti5Ysn73vtpR # GWsJr6M4KQ1SwEbZIiFZCS3A4VTbRcr7WkXets39pcpxGDlNisi+zfV95kNo09xR # hxi8SuWgb2OfQpVs/71eunp+PM1ZQsODurcy4x0/rlYJfhk53kQSMRtlfy5Cn6uY # +weWUgygBSWG/w0qanWWK5TF1DNlRKzbix6cmMuGGKcpyF7EMWE1kqmjmmu7CQvM # a3aPTqGtUt0LeqBQIhmeq/jEwd3vxQa1R85gd0/0sWxEMHkPXVfVoaryiaWAykye # 7r+c8o/41c44zs8YxdZrz72su9fqKC/TeVf5soU46ZucmH8D6f7QHy+s1ec2PEjY # l6cRIXTXHeQe # =j6cJ # -----END PGP SIGNATURE----- # gpg: Signature made Wed 10 May 2023 09:05:26 AM BST # gpg: using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653 # gpg: issuer "armbru@redhat.com" # gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [undefined] # gpg: aka "Markus Armbruster <armbru@pond.sub.org>" [undefined] # gpg: WARNING: This key is not certified with a trusted signature! # gpg: There is no indication that the signature belongs to the owner. # Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867 4E5F 3870 B400 EB91 8653 * tag 'pull-qapi-2023-05-09-v2' of https://repo.or.cz/qemu/armbru: qapi: Reformat doc comments to conform to current conventions qga/qapi-schema: Reformat doc comments to conform to current conventions docs/devel/qapi-code-gen: Update doc comment conventions qapi: Section parameter @indent is no longer used, drop qapi: Relax doc string @name: description indentation rules qapi: Rewrite parsing of doc comment section symbols and tags qapi: Fix argument description indentation stripping tests/qapi-schema/doc-good: Improve argument description tests tests/qapi-schema/doc-good: Improve a comment qapi/dump: Indent bulleted lists consistently qapi: Tidy up a slightly awkward TODO comment sphinx/qapidoc: Do not emit TODO sections into user manuals Revert "qapi: BlockExportRemoveMode: move comments to TODO" meson: Fix to make QAPI generator output depend on main.py qapi: Fix crash on stray double quote character docs/devel/qapi-code-gen: Turn FIXME admonitions into comments docs/devel/qapi-code-gen: Clean up use of quotes a bit Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
This commit is contained in:
Richard Henderson
commit
568992e344
48 changed files with 4837 additions and 4378 deletions
|
|
@ -947,6 +947,11 @@ Example::
|
|||
# <- get that
|
||||
##
|
||||
|
||||
For legibility, wrap text paragraphs so every line is at most 70
|
||||
characters long.
|
||||
|
||||
Separate sentences with two spaces.
|
||||
|
||||
|
||||
Definition documentation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
|
@ -963,57 +968,46 @@ commands and events), member (for structs and unions), branch (for
|
|||
alternates), or value (for enums), a description of each feature (if
|
||||
any), and finally optional tagged sections.
|
||||
|
||||
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::
|
||||
Descriptions start with '\@name:'. The description text should be
|
||||
indented like this::
|
||||
|
||||
# @argone:
|
||||
# This is a two line description
|
||||
# in the first style.
|
||||
#
|
||||
# @argtwo: This is a two line description
|
||||
# in the second style.
|
||||
# @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
|
||||
# do eiusmod tempor incididunt ut labore et dolore magna aliqua.
|
||||
|
||||
The number of spaces between the ':' and the text is not significant.
|
||||
.. FIXME The parser accepts these things in almost any order.
|
||||
|
||||
.. admonition:: FIXME
|
||||
|
||||
The parser accepts these things in almost any order.
|
||||
|
||||
.. admonition:: FIXME
|
||||
|
||||
union branches should be described, too.
|
||||
.. FIXME union branches should be described, too.
|
||||
|
||||
Extensions added after the definition was first released carry a
|
||||
'(since x.y.z)' comment.
|
||||
"(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.
|
||||
|
||||
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, in the same way as
|
||||
multiline argument descriptions.
|
||||
The second and subsequent lines of sections other than
|
||||
"Example"/"Examples" should be indented like this::
|
||||
|
||||
A 'Since: x.y.z' tagged section lists the release that introduced the
|
||||
# Note: Ut enim ad minim veniam, quis nostrud exercitation ullamco
|
||||
# laboris nisi ut aliquip ex ea commodo consequat.
|
||||
#
|
||||
# Duis aute irure dolor in reprehenderit in voluptate velit esse
|
||||
# cillum dolore eu fugiat nulla pariatur.
|
||||
|
||||
A "Since: x.y.z" tagged section lists the release that introduced the
|
||||
definition.
|
||||
|
||||
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.
|
||||
An "Example" or "Examples" section is rendered entirely
|
||||
as literal fixed-width text. "TODO" sections are not rendered at all
|
||||
(they are for developers, not users of QMP). In other sections, the
|
||||
text is formatted, and rST markup can be used.
|
||||
|
||||
For example::
|
||||
|
||||
|
|
@ -1023,7 +1017,7 @@ For example::
|
|||
# Statistics of a virtual block device or a block backing device.
|
||||
#
|
||||
# @device: If the stats are for a virtual block device, the name
|
||||
# corresponding to the virtual block device.
|
||||
# corresponding to the virtual block device.
|
||||
#
|
||||
# @node-name: The node name of the device. (since 2.3)
|
||||
#
|
||||
|
|
@ -1040,8 +1034,8 @@ For example::
|
|||
#
|
||||
# Query the @BlockStats for all virtual block devices.
|
||||
#
|
||||
# @query-nodes: If true, the command will query all the
|
||||
# block nodes ... explain, explain ... (since 2.3)
|
||||
# @query-nodes: If true, the command will query all the block nodes
|
||||
# ... explain, explain ... (since 2.3)
|
||||
#
|
||||
# Returns: A list of @BlockStats for each virtual block devices.
|
||||
#
|
||||
|
|
@ -1078,10 +1072,14 @@ Indentation matters. Bad example::
|
|||
|
||||
# @none: None (no memory side cache in this proximity domain,
|
||||
# or cache associativity unknown)
|
||||
# (since 5.0)
|
||||
|
||||
The description is parsed as a definition list with term "None (no
|
||||
memory side cache in this proximity domain," and definition "or cache
|
||||
associativity unknown)".
|
||||
The last line's de-indent is wrong. The second and subsequent lines
|
||||
need to line up with each other, like this::
|
||||
|
||||
# @none: None (no memory side cache in this proximity domain,
|
||||
# or cache associativity unknown)
|
||||
# (since 5.0)
|
||||
|
||||
Section tags are case-sensitive and end with a colon. Good example::
|
||||
|
||||
|
|
|
|||
|
|
@ -268,6 +268,9 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
|
|||
"""Return list of doctree nodes for additional sections"""
|
||||
nodelist = []
|
||||
for section in doc.sections:
|
||||
if section.name and section.name == 'TODO':
|
||||
# Hide TODO: sections
|
||||
continue
|
||||
snode = self._make_section(section.name)
|
||||
if section.name and section.name.startswith('Example'):
|
||||
snode += self._nodes_for_example(section.text)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue