Vladimir Sementsov-Ogievskiy recently posted
Subject: [PATCH v2 00/33] qapi: docs: width=70 and two spaces between
sentences
Date: Sat, 11 Oct 2025 17:04:06 +0300
Message-ID: <[email protected]>
His series refills doc comments to conform to the 70 width limit,
tidies up spaces between sentences, and adds code to enforce both
going forward.
In review, we agreed to only refill prose, not the examples, at least
for now. Vladimir volunteered to adjust his validation code,
accordingly. I volunteered to take care of the doc comment cleanup.
I decided redoing the cleanup would be less work than splitting.
While doing so, I found a markup bug: PATCH 1. PATCH 2+4 are the
cleanup. PATCH 3+5 additionally clean up blank lines.
Testing this with his validation code failed:
docs/interop/firmware.json also needs the treatment, and
docs/interop/vhost-user.json would if we bothered to test it. PATCH
6+7 take care of both. PATCH 8 adds proper markup to literal blocks,
so that the validation code can skip them. PATCH 9 adds the missing
test.
Vladimir's revised validation code is here:
Subject: [PATCH v5] qapi: Add documentation format validation
Date: Fri, 31 Oct 2025 21:31:29 +0300
Message-ID: <[email protected]>
It builds fine when applied it on top of this series.
v2:
* Rebased
* [PATCH 1]: Commit message tidied up [Vladimir]
* [PATCH 6+7]: "Example" section conversion split off [Vladimir]
Markus Armbruster (9):
qapi/audio: Fix description markup of AudiodevDBusOptions @nsamples
qapi: Refill doc comments to conform to conventions
qapi: Clean up whitespace between definitions
qga/qapi-schema: Refill doc comments to conform to conventions
qga/qapi-schema: Clean up whitespace between definitions
docs/interop: Refill QAPI doc comments to conform to conventions
docs/interop/firmware: Belatedly convert "Example" section
docs/interop/firmware: Literal block markup
docs/interop: Add test to keep vhost-user.json sane
docs/interop/firmware.json | 454 +++++++++++++++++------------------
docs/interop/vhost-user.json | 59 +++--
docs/meson.build | 9 +-
qapi/accelerator.json | 3 +-
qapi/acpi-hest.json | 5 +-
qapi/audio.json | 4 +-
qapi/block-core.json | 158 ++++++------
qapi/block-export.json | 26 +-
qapi/char.json | 1 -
qapi/crypto.json | 8 +-
qapi/cxl.json | 1 -
qapi/introspect.json | 8 +-
qapi/job.json | 30 +--
qapi/machine-common.json | 4 +-
qapi/machine-s390x.json | 4 +-
qapi/machine.json | 49 ++--
qapi/migration.json | 126 +++++-----
qapi/misc-i386.json | 2 -
qapi/net.json | 26 +-
qapi/qdev.json | 4 +-
qapi/qom.json | 47 ++--
qapi/run-state.json | 20 +-
qapi/sockets.json | 30 +--
qapi/stats.json | 4 +-
qapi/ui.json | 17 +-
qapi/virtio.json | 6 +-
qga/qapi-schema.json | 96 ++++----
27 files changed, 623 insertions(+), 578 deletions(-)
--
2.49.0
