[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 2/3] docs/devel/qapi-code-gen: Belatedly document feature document
[PULL 2/3] docs/devel/qapi-code-gen: Belatedly document feature documentation
Wed, 10 Nov 2021 07:19:01 +0100
Commit 6a8c0b5102 "qapi: Add feature flags to struct types" neglected
to document how to document feature flags. Make up for that.
Cc: Kevin Wolf <email@example.com>
Signed-off-by: Markus Armbruster <firstname.lastname@example.org>
[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
@@ -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
+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
# This is a two line description
@@ -986,6 +987,12 @@ The number of spaces between the ':' and the text is not
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
+ # 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.