Peter Maydell <peter.mayd...@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.hender...@linaro.org> > Signed-off-by: Peter Maydell <peter.mayd...@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: > > ##
