Move the features text down to where it would appear in-order in a QAPI documentation block, and expand it into its own subsection separate from member/arg/etc descriptions.
This draft refers back to the "Descriptions" section to make it clear that they are syntactically related, but has otherwise broken the section out into its own discrete thing to make it clear that it is an entirely separate section (group of sections). The key element here is that Descriptions and Feature Descriptions have been split apart so that they can each occupy their correct relative position in the docs that mirrors their appearance in actual documentation. (i.e. members - returns - errors - features, in that order.) Signed-off-by: John Snow <[email protected]> --- docs/devel/qapi-code-gen.rst | 32 +++++++++++++++++++++----------- 1 file changed, 21 insertions(+), 11 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 7e7b11d01df..febe8af49f9 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -987,9 +987,10 @@ definition must have documentation. Definition documentation starts with a description naming the definition with an optional indented overview, :ref:`descriptions <doc-descrip>` of each argument (for commands and events), member (for -structs and unions), branch (for alternates), or value (for enums), a -description of each feature (if any), and finally optional tagged -sections. +structs and unions), branch (for alternates), or value (for enums), +:ref:`feature descriptions <doc-feat>` of each feature (if any), and +finally optional tagged sections. + .. _doc-descrip: @@ -1013,14 +1014,6 @@ The description text must be indented like this:: Extensions added after the definition was first released carry a "(since x.y)" comment. -The feature descriptions must be preceded by a blank line and then a -line "Features:", like this:: - - # - # Features: - # - # @feature: Description text - .. _doc-tagged: @@ -1074,6 +1067,23 @@ detailing a relevant error condition. For example:: # - Any other error returns a GenericError. +.. _doc-feat: + +Feature Descriptions +^^^^^^^^^^^^^^^^^^^^ + +Feature descriptions are a :ref:`doc-descrip` section that document features +that apply to this definition. + +The feature descriptions must be preceded by a blank line and then a +line "Features:", like this:: + + # + # Features: + # + # @feature: Description text + + Details ^^^^^^^ -- 2.55.0
