[v1] qapi: docs: width=70 and two spaces between sentences

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

Posted by Vladimir Sementsov-Ogievskiy 1 month ago

Hi all!

Let's bring the documentation in line with the requirements. And
do check these requirements in QAPI parser, to avoid later
further violations.

Vladimir Sementsov-Ogievskiy (33):
  qapi: Add documentation format validation
  qapi/acpi.json: docs: width=70 and two spaces between sentences
  qapi/audio.json: docs: width=70 and two spaces between sentences
  qapi/block-core.json: docs: width=70 and two spaces between sentences
  qapi/block-export.json: docs: width=70 and two spaces between
    sentences
  qapi/block.json: docs: width=70 and two spaces between sentences
  qapi/char.json: docs: width=70 and two spaces between sentences
  qapi/crypto.json: docs: width=70 and two spaces between sentences
  qapi/dump.json: docs: width=70 and two spaces between sentences
  qapi/introspect.json: docs: width=70 and two spaces between sentences
  qapi/job.json: docs: width=70 and two spaces between sentences
  qapi/machine-s390x.json: docs: width=70 and two spaces between
    sentences
  qapi/machine.json: docs: width=70 and two spaces between sentences
  qapi/migration.json: docs: width=70 and two spaces between sentences
  qapi/misc-arm.json: docs: width=70 and two spaces between sentences
  qapi/misc-i386.json: docs: width=70 and two spaces between sentences
  qapi/misc.json: docs: width=70 and two spaces between sentences
  qapi/net.json: docs: width=70 and two spaces between sentences
  qapi/qdev.json: docs: width=70 and two spaces between sentences
  qapi/qom.json: docs: width=70 and two spaces between sentences
  qapi/replay.json: docs: width=70 and two spaces between sentences
  qapi/rocker.json: docs: width=70 and two spaces between sentences
  qapi/run-state.json: docs: width=70 and two spaces between sentences
  qapi/sockets.json: docs: width=70 and two spaces between sentences
  qapi/stats.json: docs: width=70 and two spaces between sentences
  qapi/tpm.json: docs: width=70 and two spaces between sentences
  qapi/trace.json: docs: width=70 and two spaces between sentences
  qapi/transaction.json: docs: width=70 and two spaces between sentences
  qapi/ui.json: docs: width=70 and two spaces between sentences
  qapi/vfio.json: docs: width=70 and two spaces between sentences
  qapi/virtio.json: docs: width=70 and two spaces between sentences
  qga/qapi-schema.json: docs: width=70 and two spaces between sentences
  qapi/acpi-hest.json: docs: width=70 and two spaces between sentences

 qapi/acpi-hest.json     |   2 +-
 qapi/acpi.json          |  20 ++-
 qapi/audio.json         |   4 +-
 qapi/block-core.json    | 191 +++++++++++++++-------------
 qapi/block-export.json  |  26 ++--
 qapi/block.json         |  18 +--
 qapi/char.json          |  34 +++--
 qapi/crypto.json        |   7 +-
 qapi/dump.json          |   9 +-
 qapi/introspect.json    |   8 +-
 qapi/job.json           |  26 ++--
 qapi/machine-s390x.json |   3 +-
 qapi/machine.json       |  59 +++++----
 qapi/migration.json     | 209 ++++++++++++++++++-------------
 qapi/misc-arm.json      |   6 +-
 qapi/misc-i386.json     |   9 +-
 qapi/misc.json          |  16 ++-
 qapi/net.json           |  61 +++++----
 qapi/qdev.json          |  13 +-
 qapi/qom.json           |  31 +++--
 qapi/replay.json        |   9 +-
 qapi/rocker.json        |  18 ++-
 qapi/run-state.json     |  60 +++++----
 qapi/sockets.json       |  34 ++---
 qapi/stats.json         |   3 +-
 qapi/tpm.json           |   3 +-
 qapi/trace.json         |   3 +-
 qapi/transaction.json   |  33 ++---
 qapi/ui.json            | 108 ++++++++++------
 qapi/vfio.json          |   3 +-
 qapi/virtio.json        | 269 +++-------------------------------------
 qga/qapi-schema.json    |  83 +++++++------
 scripts/qapi/parser.py  |  39 +++++-
 33 files changed, 713 insertions(+), 704 deletions(-)

-- 
2.48.1

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

Posted by Thomas Huth 1 month ago

On 11/10/2025 15.56, Vladimir Sementsov-Ogievskiy wrote:
> Hi all!
> 
> Let's bring the documentation in line with the requirements. And
> do check these requirements in QAPI parser, to avoid later
> further violations.
> 
> Vladimir Sementsov-Ogievskiy (33):
>    qapi: Add documentation format validation
>    qapi/acpi.json: docs: width=70 and two spaces between sentences
>    qapi/audio.json: docs: width=70 and two spaces between sentences
>    qapi/block-core.json: docs: width=70 and two spaces between sentences
>    qapi/block-export.json: docs: width=70 and two spaces between
>      sentences
>    qapi/block.json: docs: width=70 and two spaces between sentences
>    qapi/char.json: docs: width=70 and two spaces between sentences
>    qapi/crypto.json: docs: width=70 and two spaces between sentences
>    qapi/dump.json: docs: width=70 and two spaces between sentences
>    qapi/introspect.json: docs: width=70 and two spaces between sentences
>    qapi/job.json: docs: width=70 and two spaces between sentences
>    qapi/machine-s390x.json: docs: width=70 and two spaces between
>      sentences
>    qapi/machine.json: docs: width=70 and two spaces between sentences
>    qapi/migration.json: docs: width=70 and two spaces between sentences
>    qapi/misc-arm.json: docs: width=70 and two spaces between sentences
>    qapi/misc-i386.json: docs: width=70 and two spaces between sentences
>    qapi/misc.json: docs: width=70 and two spaces between sentences
>    qapi/net.json: docs: width=70 and two spaces between sentences
>    qapi/qdev.json: docs: width=70 and two spaces between sentences
>    qapi/qom.json: docs: width=70 and two spaces between sentences
>    qapi/replay.json: docs: width=70 and two spaces between sentences
>    qapi/rocker.json: docs: width=70 and two spaces between sentences
>    qapi/run-state.json: docs: width=70 and two spaces between sentences
>    qapi/sockets.json: docs: width=70 and two spaces between sentences
>    qapi/stats.json: docs: width=70 and two spaces between sentences
>    qapi/tpm.json: docs: width=70 and two spaces between sentences
>    qapi/trace.json: docs: width=70 and two spaces between sentences
>    qapi/transaction.json: docs: width=70 and two spaces between sentences
>    qapi/ui.json: docs: width=70 and two spaces between sentences
>    qapi/vfio.json: docs: width=70 and two spaces between sentences
>    qapi/virtio.json: docs: width=70 and two spaces between sentences
>    qga/qapi-schema.json: docs: width=70 and two spaces between sentences
>    qapi/acpi-hest.json: docs: width=70 and two spaces between sentences

Oh my, that's a lot of code churn for very few gain. Why do we have a 
different standard (70 columns) for qapi docs than for the rest of the code 
(80 columns)? That's confusing and will always cause mistakes in the future, 
I guess...

  Thomas

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

Posted by Vladimir Sementsov-Ogievskiy 1 month ago

On 13.10.25 09:11, Thomas Huth wrote:
> That's confusing and will always cause mistakes in the future, I guess...

No, that will not, look at first commit.

   [PATCH 01/33] qapi: Add documentation format validation

it adds a check into QAPI generator.

-- 
Best regards,
Vladimir

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

Posted by Vladimir Sementsov-Ogievskiy 1 month ago

On 13.10.25 09:11, Thomas Huth wrote:
> On 11/10/2025 15.56, Vladimir Sementsov-Ogievskiy wrote:
>> Hi all!
>>
>> Let's bring the documentation in line with the requirements. And
>> do check these requirements in QAPI parser, to avoid later
>> further violations.
>>
>> Vladimir Sementsov-Ogievskiy (33):
>>    qapi: Add documentation format validation
>>    qapi/acpi.json: docs: width=70 and two spaces between sentences
>>    qapi/audio.json: docs: width=70 and two spaces between sentences
>>    qapi/block-core.json: docs: width=70 and two spaces between sentences
>>    qapi/block-export.json: docs: width=70 and two spaces between
>>      sentences
>>    qapi/block.json: docs: width=70 and two spaces between sentences
>>    qapi/char.json: docs: width=70 and two spaces between sentences
>>    qapi/crypto.json: docs: width=70 and two spaces between sentences
>>    qapi/dump.json: docs: width=70 and two spaces between sentences
>>    qapi/introspect.json: docs: width=70 and two spaces between sentences
>>    qapi/job.json: docs: width=70 and two spaces between sentences
>>    qapi/machine-s390x.json: docs: width=70 and two spaces between
>>      sentences
>>    qapi/machine.json: docs: width=70 and two spaces between sentences
>>    qapi/migration.json: docs: width=70 and two spaces between sentences
>>    qapi/misc-arm.json: docs: width=70 and two spaces between sentences
>>    qapi/misc-i386.json: docs: width=70 and two spaces between sentences
>>    qapi/misc.json: docs: width=70 and two spaces between sentences
>>    qapi/net.json: docs: width=70 and two spaces between sentences
>>    qapi/qdev.json: docs: width=70 and two spaces between sentences
>>    qapi/qom.json: docs: width=70 and two spaces between sentences
>>    qapi/replay.json: docs: width=70 and two spaces between sentences
>>    qapi/rocker.json: docs: width=70 and two spaces between sentences
>>    qapi/run-state.json: docs: width=70 and two spaces between sentences
>>    qapi/sockets.json: docs: width=70 and two spaces between sentences
>>    qapi/stats.json: docs: width=70 and two spaces between sentences
>>    qapi/tpm.json: docs: width=70 and two spaces between sentences
>>    qapi/trace.json: docs: width=70 and two spaces between sentences
>>    qapi/transaction.json: docs: width=70 and two spaces between sentences
>>    qapi/ui.json: docs: width=70 and two spaces between sentences
>>    qapi/vfio.json: docs: width=70 and two spaces between sentences
>>    qapi/virtio.json: docs: width=70 and two spaces between sentences
>>    qga/qapi-schema.json: docs: width=70 and two spaces between sentences
>>    qapi/acpi-hest.json: docs: width=70 and two spaces between sentences
> 
> Oh my, that's a lot of code churn for very few gain. Why do we have a different standard (70 columns) for qapi docs than for the rest of the code (80 columns)? That's confusing and will always cause mistakes in the future, I guess...
> 

Note, I've sent "[PATCH v2 00/33] qapi: docs: width=70 and two spaces between sentences", with not doubled patches (again, sorry for that :/.

That since 9d167491cb2577d "docs/devel/qapi-code-gen: Update doc comment conventions" (2023), by Markus, written in
qapi-code-gen.rst:

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

     Separate sentences with two spaces.

And I always forget it, when preparing my patches. Checking these rules during review, and than fixing is rather boring,
so, I decided to try fix them all. Assised by AI, of course... Or, maybe AI assisted by me.

If we decide, that it is too huge, we can proceed with some list of exclusions, to cover existing violations and avoid new ones.


-- 
Best regards,
Vladimir