[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v5 15/20] docs/devel/qapi-code-gen.txt: Update to new rST bac
Re: [PATCH v5 15/20] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions
Thu, 17 Sep 2020 11:24:47 +0200
Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux)
Peter Maydell <firstname.lastname@example.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 :)
> 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.
> * 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.
> * headings and subheadings must now be in a freeform
> documentation comment of their own
> * 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.
> Reviewed-by: Richard Henderson <email@example.com>
> Signed-off-by: Peter Maydell <firstname.lastname@example.org>
> docs/devel/qapi-code-gen.txt | 90 ++++++++++++++++++++++++------------
> 1 file changed, 61 insertions(+), 29 deletions(-)
> diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
> index 69eede6c283..263f1c0b44c 100644
> --- a/docs/devel/qapi-code-gen.txt
> +++ b/docs/devel/qapi-code-gen.txt
> @@ -824,21 +824,39 @@ 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 single 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
> + ##
> +Section headings must always be correctly nested, so you can only
> +define a third-level heading inside a second-level heading, and so
> +on. The documentation generator will catch nesting mistakes and report
> +a syntax error.
Is the last sentence is useful? We don't explicitly document other
> ==== Documentation markup ====
> -Comment text starting with '=' is a section title:
> +Documentation comments can use most rST markup. In particular,
Please put two spaces after sentence-ending punctuation, for local
consistency, and to keep Emacs sentence commands working.
> +a '::' literal block can be used for examples:
> - # = Section title
> -Double the '=' for a subsection title:
> - # == Subsection title
> -'|' denotes examples:
> - # | Text of the example, may span
> - # | multiple lines
> + # ::
> + #
> + # Text of the example, may span
> + # multiple lines
> '*' starts an itemized list:
> @@ -854,37 +872,35 @@ 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 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
> -*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
> +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``'.
> -# = Section
> -# == Subsection
> -# Some text foo with *strong* and _emphasis_
> +# Some text foo with **bol** and *emphasis*
Do you mean **bold**?
> # 1. with a list
> # 2. like that
> # And some code:
> -# | $ echo foo
> -# | -> do this
> -# | <- get that
> +# ::
> +# $ echo foo
> +# -> do this
> +# <- get that
Did you mean to drop the blank line?
> ==== Definition documentation ====
> Definition documentation, if present, must immediately precede the
> @@ -899,6 +915,12 @@ commands and events), member (for structs and unions),
> branch (for
> alternates), or value (for enums), and finally optional tagged
> +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.
Is the last sentence is useful?
> FIXME: the parser accepts these things in almost any order.
> FIXME: union branches should be described, too.
> @@ -912,6 +934,16 @@ The section ends with the start of a new section.
> A 'Since: x.y.z' tagged section lists the release that introduced the
> +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:
|[Prev in Thread]
||[Next in Thread]|
- Re: [PATCH v5 15/20] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions,
Markus Armbruster <=