diff options
| author | Richard Henderson <richard.henderson@linaro.org> | 2021-11-10 11:25:03 +0100 |
|---|---|---|
| committer | Richard Henderson <richard.henderson@linaro.org> | 2021-11-10 11:25:03 +0100 |
| commit | b30187ef02d786da674cd80079e2fcd6bb8f85e1 (patch) | |
| tree | e25c0819a807d11d76c173643943bf29bf7a2e1b /docs | |
| parent | d73b6ae2c0893420c4b5d9f15b5e1407ca0d2173 (diff) | |
| parent | 8c0bae5a19478db93371570b57164c63392a2d50 (diff) | |
Merge tag 'pull-qapi-2021-11-10' of git://repo.or.cz/qemu/armbru into staging
QAPI patches patches for 2021-11-10
# gpg: Signature made Wed 10 Nov 2021 06:21:23 AM CET
# gpg: using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653
# gpg: issuer "armbru@redhat.com"
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [full]
# gpg: aka "Markus Armbruster <armbru@pond.sub.org>" [full]
* tag 'pull-qapi-2021-11-10' of git://repo.or.cz/qemu/armbru:
qapi: Belatedly mark unstable QMP parts with feature 'unstable'
docs/devel/qapi-code-gen: Belatedly document feature documentation
docs/devel/qapi-code-gen: Drop a duplicate paragraph
Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/devel/qapi-code-gen.rst | 29 |
1 files changed, 15 insertions, 14 deletions
diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 38f2d7aad3..a3b5473089 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -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 -sections. +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 +description:: # @argone: # 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 '(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. @@ -1000,12 +1007,6 @@ multiline argument descriptions. A 'Since: x.y.z' tagged section lists the release that introduced the definition. -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. - 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. |