Re: [PATCH 08/11] docs/qapi-code-gen: add "Descriptions" subsection

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> 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 <jsnow@redhat.com>
> ---
>  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.

Not this patch's fault: this isn't quite right.  The order of tagged
sections is left unspecified, which is fine now, but becomes a gap when
your "qapi: enforce section ordering" series lands.  "Details" sections
aren't mentioned at all.

>  
> -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.