This series improves the doc comment formatting rules, then reformats
doc comments to conform to them.
I don't like reformatting code. But I'm tired of looking at ugly doc
comments. People imitate them in new work (not blaming them for
that), which leads to tiresome arguments about style. I've come to
the conclusion that reformatting them is the lesser evil.
Prior discussion:
qapi: [RFC] Doc comment convention for @arg: sections
Message-ID: <87v8irv7zq.fsf@pond.sub.org>
https://lists.gnu.org/archive/html/qemu-devel/2023-03/msg05921.html
PATCH 01-12 are preliminary fixes, cleanups and test improvements,
ranging from losely related to not related at all.
PATCH 13-14 improve the QAPI generator to support the style I want.
PATCH 15 writes it down.
PATCH 16-17 reformat the doc comments to conform to it.
Markus Armbruster (17):
docs/devel/qapi-code-gen: Clean up use of quotes a bit
docs/devel/qapi-code-gen: Turn FIXME admonitions into comments
qapi: Fix crash on stray double quote character
meson: Fix to make QAPI generator output depend on main.py
Revert "qapi: BlockExportRemoveMode: move comments to TODO"
sphinx/qapidoc: Do not emit TODO sections into user manuals
qapi: Tidy up a slightly awkward TODO comment
qapi/dump: Indent bulleted lists consistently
tests/qapi-schema/doc-good: Improve a comment
tests/qapi-schema/doc-good: Improve argument description tests
qapi: Fix argument description indentation stripping
qapi: Rewrite parsing of doc comment section symbols and tags
qapi: Relax doc string @name: description indentation rules
qapi: Section parameter @indent is no longer used, drop
docs/devel/qapi-code-gen: Update doc comment conventions
qga/qapi-schema: Reformat doc comments to conform to current
conventions
qapi: Reformat doc comments to conform to current conventions
docs/devel/qapi-code-gen.rst | 74 +-
docs/sphinx/qapidoc.py | 3 +
meson.build | 2 +-
qapi/acpi.json | 50 +-
qapi/audio.json | 85 +-
qapi/authz.json | 29 +-
qapi/block-core.json | 2801 +++++++++++++------------
qapi/block-export.json | 244 ++-
qapi/block.json | 214 +-
qapi/char.json | 134 +-
qapi/common.json | 19 +-
qapi/compat.json | 13 +-
qapi/control.json | 59 +-
qapi/crypto.json | 261 ++-
qapi/cryptodev.json | 3 +
qapi/cxl.json | 74 +-
qapi/dump.json | 78 +-
qapi/error.json | 6 +-
qapi/introspect.json | 89 +-
qapi/job.json | 139 +-
qapi/machine-target.json | 303 +--
qapi/machine.json | 389 ++--
qapi/migration.json | 1120 +++++-----
qapi/misc-target.json | 67 +-
qapi/misc.json | 180 +-
qapi/net.json | 260 ++-
qapi/pci.json | 35 +-
qapi/qapi-schema.json | 25 +-
qapi/qdev.json | 63 +-
qapi/qom.json | 404 ++--
qapi/rdma.json | 1 -
qapi/replay.json | 48 +-
qapi/rocker.json | 20 +-
qapi/run-state.json | 215 +-
qapi/sockets.json | 50 +-
qapi/stats.json | 83 +-
qapi/tpm.json | 20 +-
qapi/trace.json | 34 +-
qapi/transaction.json | 87 +-
qapi/ui.json | 435 ++--
qapi/virtio.json | 84 +-
qapi/yank.json | 42 +-
qga/qapi-schema.json | 668 +++---
scripts/qapi/parser.py | 137 +-
tests/qapi-schema/doc-bad-indent.err | 2 +-
tests/qapi-schema/doc-bad-indent.json | 3 +-
tests/qapi-schema/doc-good.json | 20 +-
tests/qapi-schema/doc-good.out | 19 +-
48 files changed, 4822 insertions(+), 4369 deletions(-)
--
2.39.2