Peter Maydell <peter.mayd...@linaro.org> writes: > On Fri, 7 Feb 2020 at 08:33, Markus Armbruster <arm...@redhat.com> wrote: >> >> Peter Maydell <peter.mayd...@linaro.org> writes: >> >> > rST format requires a blank line before the start of a bulleted >> > or enumerated list. Two places in qapi-schema.json were missing >> > this blank line. >> > >> > Some places were using an indented line as a sort of single-item >> > bulleted list, which in the texinfo output comes out all run >> > onto a single line; use a real bulleted list instead. >> > >> > Some places unnecessarily indented lists, which confuses rST. >> > >> > guest-fstrim:minimum's documentation was indented the >> > right amount to share a line with @minimum, but wasn't >> > actually doing so. >> > >> > The indent on the bulleted list in the guest-set-vcpus >> > Returns section meant rST misindented it. >> > >> > Changes to the generated texinfo are very minor (the new >> > bulletted lists, and a few extra blank lines). >> > >> > Signed-off-by: Peter Maydell <peter.mayd...@linaro.org> > >> > @@ -767,17 +771,17 @@ >> > # Returns: The length of the initial sublist that has been successfully >> > # processed. The guest agent maximizes this value. Possible >> > cases: >> > # >> > -# - 0: if the @vcpus list was empty on input. Guest >> > state >> > -# has not been changed. Otherwise, >> > -# - Error: processing the first node of @vcpus failed >> > for the >> > -# reason returned. Guest state has not been >> > changed. >> > -# Otherwise, >> > +# - 0: if the @vcpus list was empty on input. Guest state >> > +# has not been changed. Otherwise, >> > +# - Error: processing the first node of @vcpus failed for the >> > +# reason returned. Guest state has not been changed. >> > +# Otherwise, >> > # - < length(@vcpus): more than zero initial nodes have been >> > processed, >> > -# but not the entire @vcpus list. Guest state >> > has >> > -# changed accordingly. To retrieve the error >> > -# (assuming it persists), repeat the call with >> > the >> > -# successfully processed initial sublist >> > removed. >> > -# Otherwise, >> > +# but not the entire @vcpus list. Guest state has >> > +# changed accordingly. To retrieve the error >> > +# (assuming it persists), repeat the call with the >> > +# successfully processed initial sublist removed. >> > +# Otherwise, >> > # - length(@vcpus): call successful. >> >> Source readability suffers a bit here. >> >> Can we break the line after the colon? >> >> # - 0: >> # if the @vcpus list was empty on input. Guest state has >> # not been changed. Otherwise, >> >> Or would a definition list be a better fit? > > A definition list does produce nicer rendering in the rST, but > it breaks the rendering in the texinfo (which interprets the > indent of a rST definition list as meaninglist and renders it > all as one long run-on paragraph). For the purposes of this > initial cleanup, I'll put in the newlines you suggest, which > have no effect on rendering output for either texinfo or rST.
Okay. We can switch to definition lists later.