Re: [PATCH v4 05/18] scripts/qapi: Move doc-comment whitespace stripping to doc.py

[Markus Armbruster]

Peter Maydell <peter.maydell@linaro.org> writes:

> As we accumulate lines from doc comments when parsing the JSON, the
> QAPIDoc class generally strips leading and trailing whitespace using
> line.strip() when it calls _append_freeform().  This is fine for
> texinfo,

Texinfo

>          but for rST leading whitespace is significant.  We'd like to
> move to having the text in doc comments be rST format rather than a
> custom syntax, so move the removal of leading whitespace from the
> QAPIDoc class to the texinfo-specific processing code in
> texi_format() in qapi/doc.py.
>
> (Trailing whitespace will always be stripped by the rstrip() in
> Section::append regardless.)

We strip to keep the Texinfo source tidier.  Stripping less as we move
towards its replacement is fine.

> In a followup commit we will make the whitespace in the lines of doc
> comment sections more consistently follow the input source.
>
> There is no change to the generated .texi files before and after this
> commit.
>
> Because the qapi-schema test checks the exact values of the
> documentation comments against a reference, we need to update that
> reference to match the new whitespace.  In the first four places this
> is now correctly checking that we did put in the amount of whitespace
> to pass a rST-formatted list to the backend; in the last two places
> the extra whitespace is 'wrong' and will go away again in the
> following commit.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

The thorough explanation in the commit message made review easier.
Thanks!

Reviewed-by: Markus Armbruster <armbru@redhat.com>