Re: [PATCH v6 17/21] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions

[Markus Armbruster]

Peter Maydell <peter.maydell@linaro.org> writes:

> Update the documentation of QAPI document comment syntax to match
> the new rST backend requirements. The principal changes are:
>  * whitespace is now significant,

Well, differently significant :)  Anyway, close enough.

>                                   and multiline definitions
>    must have their second and subsequent lines indented to
>    match the first line
>  * general rST format markup is permitted, not just the small
>    set of markup the old texinfo generator handled. For most
>    things (notably bulleted and itemized lists) the old format
>    is the same as rST was.

"was the same as rST is"?

>  * Specific things that might trip people up:
>    - instead of *bold* and _italic_ rST has **bold** and *italic*
>    - lists need a preceding and following blank line
>    - a lone literal '*' will need to be backslash-escaped to
>      avoid a rST syntax error
>  * the old leading '|' for example (literal text) blocks is
>    replaced by the standard rST '::' literal block.
>  * we support arbitrary levels of sub- and sub-sub-heading, not
>    just a main and sub-heading like the old texinfo generator

Possibly noteworthy: lists can now be nested.  Can add that in my tree.

>
> Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  docs/devel/qapi-code-gen.txt | 83 +++++++++++++++++++++++-------------
>  1 file changed, 53 insertions(+), 30 deletions(-)
>
> diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
> index 69eaffac376..7d2479dde82 100644
> --- a/docs/devel/qapi-code-gen.txt
> +++ b/docs/devel/qapi-code-gen.txt
> @@ -824,23 +824,37 @@ See below for more on definition documentation.
>  Free-form documentation may be used to provide additional text and
>  structuring content.
>  
> +==== Headings and subheadings ====
> +
> +A free-form documentation comment containing a line which starts with
> +some '=' symbols and then a space defines a section heading:
> +
> +    ##
> +    # = This is a top level heading
> +    #
> +    # This is a free-form comment which will go under the
> +    # top level heading.
> +    ##
> +
> +    ##
> +    # == This is a second level heading
> +    ##
> +
> +A heading line must be the first line of the documentation
> +comment block.
> +
> +Section headings must always be correctly nested, so you can only
> +define a third-level heading inside a second-level heading, and so on.
>  
>  ==== Documentation markup ====
>  
> -Comment text starting with '=' is a section title:
> +Documentation comments can use most rST markup.  In particular,
> +a '::' literal block can be used for examples:
>  
> -    # = Section title
> -
> -Double the '=' for a subsection title:
> -
> -    # == Subsection title
> -
> -Both are only permitted in free-form documentation.
> -
> -'|' denotes examples:
> -
> -    # | Text of the example, may span
> -    # | multiple lines
> +    # ::
> +    #
> +    #   Text of the example, may span
> +    #   multiple lines
>  
>  '*' starts an itemized list:
>  
> @@ -856,34 +870,33 @@ A decimal number followed by '.' starts a numbered list:
>      #    multiple lines
>      # 2. Second item
>  
> -The actual number doesn't matter.  You could even use '*' instead of
> -'2.' for the second item.
> +The actual number doesn't matter.
>  
> -Lists can't be nested.  Blank lines are currently not supported within
> -lists.
> +Lists of either kind must be preceded and followed by a blank line.
> +If a list item's text spans multiple lines, then the second and
> +subsequent lines must be correctly indented to line up with the
> +first character of the first line.
>  
> -Additional whitespace between the initial '#' and the comment text is
> -permitted.
> -
> -*foo* and _foo_ are for strong and emphasis styles respectively (they
> -do not work over multiple lines).  @foo is used to reference a name in
> -the schema.
> +The usual '**strong**', '*emphasised*' and '``literal``' markup should
> +be used.  If you need a single literal '*' you will need to
> +backslash-escape it.  As an extension beyond the usual rST syntax, you
> +can also use '@foo' to reference a name in the schema; this is
> +rendered the same way as '``foo``'.
>  
>  Example:
>  
>  ##
> -# = Section
> -# == Subsection
> -#
> -# Some text foo with *strong* and _emphasis_
> +# Some text foo with **bold** and *emphasis*
>  # 1. with a list
>  # 2. like that
>  #
>  # And some code:
> -# | $ echo foo
> -# | -> do this
> -# | <- get that
>  #
> +# ::
> +#
> +#   $ echo foo
> +#   -> do this
> +#   <- get that
>  ##
>  
>  

v5 had

  @@ -899,6 +915,12 @@ commands and events), member (for structs and unions), 
branch (for
   alternates), or value (for enums), and finally optional tagged
   sections.
   
  +Descriptions of arguments can span multiple lines; if they
  +do then the second and subsequent lines must be indented
  +to line up with the first character of the first line of the
  +description. The parser will report a syntax error if there
  +is insufficient indentation.
  +
   FIXME: the parser accepts these things in almost any order.
   FIXME: union branches should be described, too.
   
I questioned the value of the last sentence.  You dropped both.
Intentional?

> @@ -937,6 +950,16 @@ 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.
> +
>  For example:
>  
>  ##