[PATCH 00/17] qapi: Reformat doc comments

[Markus Armbruster <armbru@redhat.com>]

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