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

[Markus Armbruster <armbru@redhat.com>]

Daniel P. Berrangé <berrange@redhat.com> writes:

> On Sat, Oct 11, 2025 at 05:04:06PM +0300, Vladimir Sementsov-Ogievskiy wrote:
>> Hi all!
>> 
>> Let's bring the documentation in line with the requirements. And
>> do check these requirements in QAPI parser.
>
> This implicitly assumes that the requirements are desirable.
>
> This is a large number of patches, showing the requirements are widely
> ignored today. When I look at the changes in the patches my overwhealming
> reaction is that they are not beneficial, which in turn makes me believe
> the requirements should be changed to match the reality of the code,
> rather than the reverse.

A QAPI schema contains four distinct kinds of text:

1. Schema code

2. Example code in comments

3. Doc comments less example code, i.e. prose

4. Non-doc comments

This series touches all four.

"The requirements" refers to docs/devel/qapi-code-gen.rst section
Documentation comments / Documentation markup:

    For legibility, wrap text paragraphs so every line is at most 70
    characters long.

    Separate sentences with two spaces.

I've explained why these rules make sense a number of times, and I'm
happy to explain again if needed.

Note this applies only to doc comments.

I've been enforcing it manually for prose.  Whether it should be
enforced for example code is debatable.  Let's focus on prose.

"Widely ignored" is not true, and I have numbers to back that up.

We have some 20,000 lines of doc comments in the main QAPI schema and
the QGA QAPI schema.  Some 3,000 lines are examples.  That leaves a bit
over 17,000 lines of prose in 48 files.

If I drop the changes to the other three kinds from Vladimir's series,
and add a few more prose changes he missed, I get this diffstat:

 24 files changed, 351 insertions(+), 332 deletions(-)

So, 98% of the prose adheres to the rules.

Half of the files are *spotless*.