mirrors
/
qemu
mirror of https://gitlab.com/qemu-project/qemu
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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 <kwolf@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20211026111023.76937-3-armbru@redhat.com>
[Editing accident fixed]
This commit is contained in:
Markus Armbruster 2021-10-26 13:10:23 +02:00
parent 13b86cbd2c
commit 53e9e547d2
1 changed files with 15 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -956,15 +956,16 @@ definition must have documentation.
Definition documentation starts with a line naming the definition, Definition documentation starts with a line naming the definition,
followed by an optional overview, a description of each argument (for followed by an optional overview, a description of each argument (for
commands and events), member (for structs and unions), branch (for commands and events), member (for structs and unions), branch (for
alternates), or value (for enums), and finally optional tagged alternates), or value (for enums), a description of each feature (if
sections. any), and finally optional tagged sections.
Descriptions of arguments can span multiple lines. The description The description of an argument or feature 'name' starts with
text can start on the line following the '\@argname:', in which case it '\@name:'. The description text can start on the line following the
must not be indented at all. It can also start on the same line as '\@name:', in which case it must not be indented at all. It can also
the '\@argname:'. In this case if it spans multiple lines then second start on the same line as the '\@name:'. In this case if it spans
and subsequent lines must be indented to line up with the first multiple lines then second and subsequent lines must be indented to
character of the first line of the description:: line up with the first character of the first line of the
description::
# @argone: # @argone:
# This is a two line description # 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 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: 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.