Re: [PATCH v2 00/33] qapi: docs: width=70 and two spaces between sentences

[Markus Armbruster <armbru@redhat.com>]

Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> writes:

> Hi all!
>
> Let's bring the documentation in line with the requirements. And
> do check these requirements in QAPI parser.

Prior art:

    01bed0ff14 qapi: Refill doc comments to conform to conventions
    7270819384 qga/qapi-schema: Refill doc comments to conform to current conventions
    209e64d9ed qapi: Refill doc comments to conform to current conventions

These only touched prose.

Your series also touches examples, is split per source file, and adds
code to enforce the rules automatically.

Automatic enforcement makes a ton of sense.  Should've tried to code it
up long ago.  Much appreciated!  However, it's in the first patch.  It
needs to go last to not break bisection.

I don't think splitting per source file is necessary.

I'd prefer to put aside examples for now and focus on prose, since the
case for prose is much stronger.

Since I already split off the prose changes for my own review purposes,
there's no need for you to do that again.  I'll take care of it.

However, we need to adjust the enforcement code to skip examples.

Examples are marked up with ReST directive qmp-example.  They look like
this:

    # .. qmp-example::
    #
    #     the example
    #         text is
    #     indented

The stupidest solution that could possibly work is to start skipping the
checks at

    # .. qmp-example::

and resume it at the first unindented line.

This is of course a hack: it second-guesses the ReST parser.  I think
it's good enough.

If we in a later step decide reflowing the examples is usful, the hack
goes away.

Would you be willing to take care of that part?