haraldwolff/qemu-patch-raspberry4
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

docs/devel/qapi-code-gen: Reorder sections for readability

Browse source 
Section "QMP/Guest agent schema" starts with a brief introduction,
then subsection "Comments", then subsection "Schema overview" (more
elaborate introduction), and only then talks about schema entities
like types, commands, and so forth.

Subsection "Comments" is long and tiring: almost 500 words, mostly
about doc comments.  Move the doc comment part to its own subsection
"Documentation comments" at the very end of "QMP/Guest agent schema".

Subsection "Schema overview" explains naming rules at considerable
length: 250 words.  Move this part to its own subsection "Naming rules
and reserved names" right after the subsections on schema entities.

Subsection "Enumeration types" is wedged between "Struct types" and
"Union types".  Move it before "Struct types".

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20190913201349.24332-13-armbru@redhat.com>
This commit is contained in:
Markus Armbruster 2019-09-13 22:13:45 +02:00
parent 398969fe1c
commit f5821f5262
1 changed files with 221 additions and 215 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

436
docs/devel/qapi-code-gen.txt
View file

@ -50,147 +50,6 @@ schema requires the use of JSON numbers or null.
Comments are allowed; anything between an unquoted # and the following
newline is ignored.
A multi-line comment that starts and ends with a '##' line is a
documentation comment. These are parsed by the documentation
generator, which recognizes certain markup detailed below.
==== Documentation markup ====
Comment text starting with '=' is a section title:
# = Section title
Double the '=' for a subsection title:
# == Subsection title
'|' denotes examples:
# | Text of the example, may span
# | multiple lines
'*' starts an itemized list:
# * First item, may span
# multiple lines
# * Second item
You can also use '-' instead of '*'.
A decimal number followed by '.' starts a numbered list:
# 1. First item, may span
# multiple lines
# 2. Second item
The actual number doesn't matter. You could even use '*' instead of
'2.' for the second item.
Lists can't be nested. Blank lines are currently not supported within
lists.
Additional whitespace between the initial '#' and the comment text is
permitted.
*foo* and _foo_ are for strong and emphasis styles respectively (they
do not work over multiple lines). @foo is used to reference a name in
the schema.
Example:
##
# = Section
# == Subsection
#
# Some text foo with *strong* and _emphasis_
# 1. with a list
# 2. like that
#
# And some code:
# | $ echo foo
# | -> do this
# | <- get that
#
##
==== Expression documentation ====
Expressions other than include and pragma directives may be preceded
by a documentation block. Such blocks are called expression
documentation blocks.
When documentation is required (see pragma 'doc-required'), expression
documentation blocks are mandatory.
The documentation block consists of a first line naming the
expression, an optional overview, a description of each argument (for
commands and events) or member (for structs, unions and alternates),
and optional tagged sections.
FIXME: the parser accepts these things in almost any order.
Extensions added after the expression was first released carry a
'(since x.y.z)' comment.
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.
A 'Since: x.y.z' tagged section lists the release that introduced the
expression.
For example:
##
# @BlockStats:
#
# 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.
#
# @node-name: The node name of the device. (since 2.3)
#
# ... more members ...
#
# Since: 0.14.0
##
{ 'struct': 'BlockStats',
'data': {'*device': 'str', '*node-name': 'str',
... more members ... } }
##
# @query-blockstats:
#
# 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)
#
# Returns: A list of @BlockStats for each virtual block devices.
#
# Since: 0.14.0
#
# Example:
#
# -> { "execute": "query-blockstats" }
# <- {
# ... lots of output ...
# }
#
##
{ 'command': 'query-blockstats',
'data': { '*query-nodes': 'bool' },
'returns': ['BlockStats'] }
==== Free-form documentation ====
A documentation block that isn't an expression documentation block is
a free-form documentation block. These may be used to provide
additional text and structuring content.
=== Schema overview ===
@ -217,43 +76,6 @@ refers to a single-dimension array of that type; multi-dimension
arrays are not directly supported (although an array of a complex
struct that contains an array member is possible).
All names must begin with a letter, and contain only ASCII letters,
digits, hyphen, and underscore. There are two exceptions: enum values
may start with a digit, and names that are downstream extensions (see
section Downstream extensions) start with underscore.
Names beginning with 'q_' are reserved for the generator, which uses
them for munging QMP names that resemble C keywords or other
problematic strings. For example, a member named "default" in qapi
becomes "q_default" in the generated C code.
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.
Command names, and member names within a type, should be all lower
case with words separated by a hyphen. However, some existing older
commands and complex types use underscore; when extending such
expressions, consistency is preferred over blindly avoiding
underscore.
Event names should be ALL_CAPS with words separated by underscore.
Member name 'u' and names starting with 'has-' or 'has_' are reserved
for the generator, which uses them for unions and for tracking
optional members.
Any name (command, event, type, member, or enum value) beginning with
"x-" is marked experimental, and may be withdrawn or changed
incompatibly in a future release.
Pragma 'name-case-whitelist' lets you violate the rules on use of
upper and lower case. Use for new code is strongly discouraged.
In the rest of this document, usage lines are given for each
expression type, with literal strings written in lower case and
placeholders written in capitals. If a literal string includes a
@ -328,6 +150,43 @@ Pragma 'name-case-whitelist' takes a list of names that may violate
rules on use of upper- vs. lower-case letters. Default is none.
=== Enumeration types ===
Usage: { 'enum': STRING, 'data': ARRAY-OF-STRING }
{ 'enum': STRING, '*prefix': STRING, 'data': ARRAY-OF-STRING }
An enumeration type is a dictionary containing a single 'data' key
whose value is a list of strings. An example enumeration is:
{ 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }
Nothing prevents an empty enumeration, although it is probably not
useful. The list of strings should be lower case; if an enum name
represents multiple words, use '-' between words. The string 'max' is
not allowed as an enum value, and values should not be repeated.
The enum constants will be named by using a heuristic to turn the
type name into a set of underscore separated words. For the example
above, 'MyEnum' will turn into 'MY_ENUM' giving a constant name
of 'MY_ENUM_VALUE1' for the first value. If the default heuristic
does not result in a desirable name, the optional 'prefix' member
can be used when defining the enum.
The enumeration values are passed as strings over the Client JSON
Protocol, but are encoded as C enum integral values in generated code.
While the C code starts numbering at 0, it is better to use explicit
comparisons to enum values than implicit comparisons to 0; the C code
will also include a generated enum member ending in _MAX for tracking
the size of the enum, useful when using common functions for
converting between strings and enum values. Since the wire format
always passes by name, it is acceptable to reorder or add new
enumeration members in any location without breaking clients of Client
JSON Protocol; however, removing enum values would break
compatibility. For any struct that has a member that will only contain
a finite set of string values, using an enum type for that member is
better than open-coding the member to be type 'str'.
=== Struct types ===
Usage: { 'struct': STRING, 'data': DICT, '*base': STRUCT-NAME }
@ -389,43 +248,6 @@ both members like this:
"backing": "/some/place/my-backing-file" }
=== Enumeration types ===
Usage: { 'enum': STRING, 'data': ARRAY-OF-STRING }
{ 'enum': STRING, '*prefix': STRING, 'data': ARRAY-OF-STRING }
An enumeration type is a dictionary containing a single 'data' key
whose value is a list of strings. An example enumeration is:
{ 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }
Nothing prevents an empty enumeration, although it is probably not
useful. The list of strings should be lower case; if an enum name
represents multiple words, use '-' between words. The string 'max' is
not allowed as an enum value, and values should not be repeated.
The enum constants will be named by using a heuristic to turn the
type name into a set of underscore separated words. For the example
above, 'MyEnum' will turn into 'MY_ENUM' giving a constant name
of 'MY_ENUM_VALUE1' for the first value. If the default heuristic
does not result in a desirable name, the optional 'prefix' member
can be used when defining the enum.
The enumeration values are passed as strings over the Client JSON
Protocol, but are encoded as C enum integral values in generated code.
While the C code starts numbering at 0, it is better to use explicit
comparisons to enum values than implicit comparisons to 0; the C code
will also include a generated enum member ending in _MAX for tracking
the size of the enum, useful when using common functions for
converting between strings and enum values. Since the wire format
always passes by name, it is acceptable to reorder or add new
enumeration members in any location without breaking clients of Client
JSON Protocol; however, removing enum values would break
compatibility. For any struct that has a member that will only contain
a finite set of string values, using an enum type for that member is
better than open-coding the member to be type 'str'.
=== Union types ===
Usage: { 'union': STRING, 'data': DICT }
@ -744,6 +566,46 @@ This expanded form is necessary if you want to make the feature
conditional (see below in "Configuring the schema").
=== Naming rules and reserved names ===
All names must begin with a letter, and contain only ASCII letters,
digits, hyphen, and underscore. There are two exceptions: enum values
may start with a digit, and names that are downstream extensions (see
section Downstream extensions) start with underscore.
Names beginning with 'q_' are reserved for the generator, which uses
them for munging QMP names that resemble C keywords or other
problematic strings. For example, a member named "default" in qapi
becomes "q_default" in the generated C code.
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.
Command names, and member names within a type, should be all lower
case with words separated by a hyphen. However, some existing older
commands and complex types use underscore; when extending such
expressions, consistency is preferred over blindly avoiding
underscore.
Event names should be ALL_CAPS with words separated by underscore.
Member name 'u' and names starting with 'has-' or 'has_' are reserved
for the generator, which uses them for unions and for tracking
optional members.
Any name (command, event, type, member, or enum value) beginning with
"x-" is marked experimental, and may be withdrawn or changed
incompatibly in a future release.
Pragma 'name-case-whitelist' lets you violate the rules on use of
upper and lower case. Use for new code is strongly discouraged.
=== Downstream extensions ===
QAPI schema names that are externally visible, say in the Client JSON
@ -814,6 +676,150 @@ The presence of 'if' keys in the schema is reflected through to the
introspection output depending on the build configuration.
=== Documentation comments ===
A multi-line comment that starts and ends with a '##' line is a
documentation comment. These are parsed by the documentation
generator, which recognizes certain markup detailed below.
==== Documentation markup ====
Comment text starting with '=' is a section title:
# = Section title
Double the '=' for a subsection title:
# == Subsection title
'|' denotes examples:
# | Text of the example, may span
# | multiple lines
'*' starts an itemized list:
# * First item, may span
# multiple lines
# * Second item
You can also use '-' instead of '*'.
A decimal number followed by '.' starts a numbered list:
# 1. First item, may span
# multiple lines
# 2. Second item
The actual number doesn't matter. You could even use '*' instead of
'2.' for the second item.
Lists can't be nested. Blank lines are currently not supported within
lists.
Additional whitespace between the initial '#' and the comment text is
permitted.
*foo* and _foo_ are for strong and emphasis styles respectively (they
do not work over multiple lines). @foo is used to reference a name in
the schema.
Example:
##
# = Section
# == Subsection
#
# Some text foo with *strong* and _emphasis_
# 1. with a list
# 2. like that
#
# And some code:
# | $ echo foo
# | -> do this
# | <- get that
#
##
==== Expression documentation ====
Expressions other than include and pragma directives may be preceded
by a documentation block. Such blocks are called expression
documentation blocks.
When documentation is required (see pragma 'doc-required'), expression
documentation blocks are mandatory.
The documentation block consists of a first line naming the
expression, an optional overview, a description of each argument (for
commands and events) or member (for structs, unions and alternates),
and optional tagged sections.
FIXME: the parser accepts these things in almost any order.
Extensions added after the expression was first released carry a
'(since x.y.z)' comment.
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.
A 'Since: x.y.z' tagged section lists the release that introduced the
expression.
For example:
##
# @BlockStats:
#
# 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.
#
# @node-name: The node name of the device. (since 2.3)
#
# ... more members ...
#
# Since: 0.14.0
##
{ 'struct': 'BlockStats',
'data': {'*device': 'str', '*node-name': 'str',
... more members ... } }
##
# @query-blockstats:
#
# 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)
#
# Returns: A list of @BlockStats for each virtual block devices.
#
# Since: 0.14.0
#
# Example:
#
# -> { "execute": "query-blockstats" }
# <- {
# ... lots of output ...
# }
#
##
{ 'command': 'query-blockstats',
'data': { '*query-nodes': 'bool' },
'returns': ['BlockStats'] }
==== Free-form documentation ====
A documentation block that isn't an expression documentation block is
a free-form documentation block. These may be used to provide
additional text and structuring content.
== Client JSON Protocol introspection ==
Clients of a Client JSON Protocol commonly need to figure out what