Peter Maydell <peter.mayd...@linaro.org> writes: > On Tue, 29 Sep 2020 at 13:35, Markus Armbruster <arm...@redhat.com> wrote: >> >> 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 :) 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"? > > Yes :-)
Can fix in my tree. > >> 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? > > I moved the first sentence to patch 5 in v6 (ie to the patch > which updates parser.py to enforce those indentation restrictions), > so as to make patches 1..5 suitable for merging even if we needed > to respin the second half of the series. I see. >> > @@ -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. > > I also moved this paragraph into patch 5 (where it appears just > above the "A 'Since:..." text you can see in the context here) > but forgot to delete the copy of it here, so at this point it is > duplicate text and should not be in this patch. Oops. > >> > + >> > +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. > > (This patch is the right place for this paragraph.) Thanks! Reviewed-by: Markus Armbruster <arm...@redhat.com>
