Message ID | 20200810195019.25427-16-peter.maydell@linaro.org |
---|---|
State | Accepted |
Headers | show |
Series | Convert QAPI doc comments to generate rST instead of texinfo | expand |
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 :) > 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 <richard.henderson@linaro.org> > Signed-off-by: Peter Maydell <peter.maydell@linaro.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 parse errors. > > ==== 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. > +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. Long line. > +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 **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 > 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. 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 > 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: > > ##
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. ==== 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 - -'|' 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. +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 **bol** and *emphasis* # 1. with a list # 2. like that # # And some code: -# | $ echo foo -# | -> do this -# | <- get that # +# :: +# +# $ echo foo +# -> do this +# <- get that ## - ==== 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 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. @@ -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 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: ##