Section off the part of the spec that describes descriptions. Similarly to "Tagged sections", the concept of naming "Descriptions" as a proper noun might also be something we'd like to sunset, but for now I have retained the section. I believe the documentation itself is entirely valid and useful, but we may want to come up with a term for "arguments, members, branches, or values" as a group of concepts instead - excising only "Features" as something that is different.
Signed-off-by: John Snow <[email protected]> --- docs/devel/qapi-code-gen.rst | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 1897cde39cf..7e7b11d01df 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -985,13 +985,23 @@ When documentation is required (see pragma_ 'doc-required'), every definition must have documentation. Definition documentation starts with a description naming the -definition with an optional indented overview, a description 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. +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. -Descriptions start with '\@name:'. The description text must be -indented like this:: + +.. _doc-descrip: + +Descriptions +^^^^^^^^^^^^ + +Descriptions start with '\@name:'. These are used to document +arguments (for commands and events), members (for structs and unions), +branches (for alternates), or values (for enums). + +The description text must be indented like this:: # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed # do eiusmod tempor incididunt ut labore et dolore magna aliqua. -- 2.55.0
