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
