SYS-OSS/FRET-qemu
4
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs/devel/qapi-code-gen: Update doc comment conventions

Browse Source 
The commit before previous relaxed the indentation rules to let us
improve the doc comment conventions.  This commit changes the written
conventions.  The next commits will update QAPI schemas to conform to
them.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-16-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
This commit is contained in:
Markus Armbruster 2023-04-28 12:54:27 +02:00
parent eb59cf7628
commit 9d167491cb
1 changed files with 22 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
docs/devel/qapi-code-gen.rst
View File

@ -947,6 +947,11 @@ Example::
# <- get that # <- get that
## ##
For legibility, wrap text paragraphs so every line is at most 70
characters long.
Separate sentences with two spaces.
Definition documentation Definition documentation
~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~
@ -963,22 +968,12 @@ commands and events), member (for structs and unions), branch (for
alternates), or value (for enums), a description of each feature (if alternates), or value (for enums), a description of each feature (if
any), and finally optional tagged sections. any), and finally optional tagged sections.
The description of an argument or feature 'name' starts with Descriptions start with '\@name:'. The description text should be
'\@name:'. The description text can start on the line following the indented like this::
'\@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: # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
# This is a two line description # do eiusmod tempor incididunt ut labore et dolore magna aliqua.
# in the first style.
#
# @argtwo: This is a two line description
# in the second style.
The number of spaces between the ':' and the text is not significant.
.. FIXME The parser accepts these things in almost any order. .. FIXME The parser accepts these things in almost any order.
.. FIXME union branches should be described, too. .. FIXME union branches should be described, too.
@ -990,23 +985,26 @@ The feature descriptions must be preceded by a line "Features:", like
this:: this::
# Features: # Features:
#
# @feature: Description text # @feature: Description text
A tagged section starts with one of the following words: A tagged section starts with one of the following words:
"Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:". "Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:".
The section ends with the start of a new section. The section ends with the start of a new section.
The text of a section can start on a new line, in The second and subsequent lines of sections other than
which case it must not be indented at all. It can also start "Example"/"Examples" should be indented like this::
on the same line as the "Note:", "Returns:", etc tag. In this
case if it spans multiple lines then second and subsequent # Note: Ut enim ad minim veniam, quis nostrud exercitation ullamco
lines must be indented to match the first, in the same way as # laboris nisi ut aliquip ex ea commodo consequat.
multiline argument descriptions. #
# 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 A "Since: x.y.z" tagged section lists the release that introduced the
definition. definition.
An "Example" or "Examples" section is automatically rendered entirely An "Example" or "Examples" section is rendered entirely
as literal fixed-width text. "TODO" sections are not rendered at all as literal fixed-width text. "TODO" sections are not rendered at all
(they are for developers, not users of QMP). In other sections, the (they are for developers, not users of QMP). In other sections, the
text is formatted, and rST markup can be used. text is formatted, and rST markup can be used.
@ -1019,7 +1017,7 @@ For example::
# Statistics of a virtual block device or a block backing device. # Statistics of a virtual block device or a block backing device.
# #
# @device: If the stats are for a virtual block device, the name # @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) # @node-name: The node name of the device. (since 2.3)
# #
@ -1036,8 +1034,8 @@ For example::
# #
# Query the @BlockStats for all virtual block devices. # Query the @BlockStats for all virtual block devices.
# #
# @query-nodes: If true, the command will query all the # @query-nodes: If true, the command will query all the block nodes
# block nodes ... explain, explain ... (since 2.3) # ... explain, explain ... (since 2.3)
# #
# Returns: A list of @BlockStats for each virtual block devices. # Returns: A list of @BlockStats for each virtual block devices.
# #