Skip to content

qapi: Reformat doc comments

Markus Armbruster qemu-devel 1 version In review

Get series with b4
b4 am [email protected]

Versions newest first

  1. v1 Latest17 patches 30 repliesIn review

Patches in v1 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/17docs/devel/qapi-code-gen: Clean up use of quotes a bitdocs/devel/qapi-code-gen.rst+6 -61 reply
2/17docs/devel/qapi-code-gen: Turn FIXME admonitions into commentsdocs/devel/qapi-code-gen.rst+2 -71 reply
3/17qapi: Fix crash on stray double quote characterscripts/qapi/parser.py+1 -12 replies
4/17meson: Fix to make QAPI generator output depend on main.pymeson.build+1 -12 replies
5/17Revert "qapi: BlockExportRemoveMode: move comments to TODO"qapi/block-export.json+5 -51 reply
6/17sphinx/qapidoc: Do not emit TODO sections into user manualsdocs/devel/qapi-code-gen.rst docs/sphinx/qapidoc.py+6 -22 replies
7/17qapi: Tidy up a slightly awkward TODO commentqapi/migration.json+3 -23 replies
8/17qapi/dump: Indent bulleted lists consistentlyqapi/dump.json+6 -61 reply
9/17tests/qapi-schema/doc-good: Improve a commenttests/qapi-schema/doc-good.json tests/qapi-schema/doc-good.out+5 -11 reply
10/17tests/qapi-schema/doc-good: Improve argument description teststests/qapi-schema/doc-good.json tests/qapi-schema/doc-good.out+18 -133 replies
11/17qapi: Fix argument description indentation strippingscripts/qapi/parser.py tests/qapi-schema/doc-good.out+12 -101 reply
12/17qapi: Rewrite parsing of doc comment section symbols and tagsscripts/qapi/parser.py+23 -283 replies
13/17qapi: Relax doc string @name: description indentation rulesdocs/devel/qapi-code-gen.rst scripts/qapi/parser.py tests/qapi-schema/doc-bad-indent.err +3 more+32 -623 replies
14/17qapi: Section parameter @indent is no longer used, dropscripts/qapi/parser.py+14 -171 reply
15/17docs/devel/qapi-code-gen: Update doc comment conventionsdocs/devel/qapi-code-gen.rst+22 -241 reply
16/17qga/qapi-schema: Reformat doc comments to conform to current conventionsqga/qapi-schema.json+382 -2861 reply
17/17qapi: Reformat doc comments to conform to current conventionsqapi/acpi.json qapi/audio.json qapi/authz.json +36 more+4322 -39362 replies

Reviews trailers per patch

All 17 patches have a Reviewed-by or Acked-by.

PatchJuan QuintelaAni SinhaLukas StraubPhilippe Mathieu-Daudé
1/17R-b
2/17R-b
3/17R-b
4/17R-b
5/17R-b
6/17R-b R-b
7/17R-b R-b
8/17R-b
9/17R-b
10/17R-b
11/17R-b
12/17R-b
13/17R-b R-b
14/17R-b
15/17R-b
16/17R-b
17/17R-b A-b

Trailers given in replies are filled; those carried in the patches from earlier versions are outlined with dashes. Scroll the table sideways for all 4 reviewers.

Read the v1 thread

Cover letter [PATCH 00/17] qapi: Reformat doc comments

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: <[email protected]>
    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(-)
Signature · 1 line
2.39.2