mbox series

[00/16] qapi: Doc comment parsing & doc generation work

Message ID 20240216145841.2099240-1-armbru@redhat.com
Headers show
Series qapi: Doc comment parsing & doc generation work | expand

Message

Markus Armbruster Feb. 16, 2024, 2:58 p.m. UTC 
This series tightens doc comment syntax, and makes the doc comment
parser easier to maintain.

* PATCH 01-03: Fix and extend tests
* PATCH 04: Drop dead code
* PATCH 05-07: Improve error messages
* PATCH 08-13: Clean up code and tighten doc comment syntax
* PATCH 14: Rewrite the doc comment parser
* PATCH 15-16: Clean up code and tighten doc comment syntax some more

The diffstat is deceptive.  Most of it is due to PATCH 10 indenting
examples.  With whitespace ignored (-w), it's just

 34 files changed, 328 insertions(+), 335 deletions(-)


Markus Armbruster (16):
  tests/qapi-schema: Fix test 'QAPI rST doc'
  tests/qapi-schema: Cover duplicate 'Features:' line
  tests/qapi-schema: Cover 'Features:' not followed by descriptions
  sphinx/qapidoc: Drop code to generate doc for simple union branch
  qapi: Improve error position for bogus argument descriptions
  qapi: Improve error position for bogus invalid "Returns" section
  qapi: Improve error message for empty doc sections
  qapi: Rename QAPIDoc.Section.name to .tag
  qapi: Reject section heading in the middle of a doc comment
  qapi: Require descriptions and tagged sections to be indented
  qapi: Recognize section tags and 'Features:' only after blank line
  qapi: Call QAPIDoc.check() always
  qapi: Merge adjacent untagged sections
  qapi: Rewrite doc comment parser
  qapi: Reject multiple and empty feature descriptions
  qapi: Divorce QAPIDoc from QAPIParseError

 docs/devel/qapi-code-gen.rst                  |  30 +-
 docs/sphinx/qapidoc.py                        |  28 +-
 qapi/acpi.json                                |  20 +-
 qapi/block-core.json                          | 868 +++++++++---------
 qapi/block.json                               | 274 +++---
 qapi/char.json                                | 172 ++--
 qapi/control.json                             |  54 +-
 qapi/dump.json                                |  26 +-
 qapi/machine-target.json                      |   6 +-
 qapi/machine.json                             | 302 +++---
 qapi/migration.json                           | 690 +++++++-------
 qapi/misc-target.json                         | 110 +--
 qapi/misc.json                                | 172 ++--
 qapi/net.json                                 | 118 +--
 qapi/pci.json                                 | 252 ++---
 qapi/qdev.json                                |  38 +-
 qapi/qom.json                                 |  54 +-
 qapi/rdma.json                                |  14 +-
 qapi/replay.json                              |  16 +-
 qapi/rocker.json                              |  66 +-
 qapi/run-state.json                           |  86 +-
 qapi/tpm.json                                 |  36 +-
 qapi/trace.json                               |  12 +-
 qapi/transaction.json                         |  36 +-
 qapi/ui.json                                  | 324 +++----
 qapi/virtio.json                              | 778 ++++++++--------
 qapi/yank.json                                |  24 +-
 scripts/qapi/parser.py                        | 517 +++++------
 scripts/qapi/schema.py                        |   7 +-
 .../qapi-schema/doc-bad-alternate-member.err  |   2 +-
 .../qapi-schema/doc-bad-boxed-command-arg.err |   2 +-
 tests/qapi-schema/doc-bad-command-arg.err     |   2 +-
 tests/qapi-schema/doc-bad-enum-member.err     |   2 +-
 tests/qapi-schema/doc-bad-event-arg.err       |   2 +-
 tests/qapi-schema/doc-bad-feature.err         |   2 +-
 tests/qapi-schema/doc-bad-union-member.err    |   2 +-
 tests/qapi-schema/doc-duplicate-features.err  |   1 +
 tests/qapi-schema/doc-duplicate-features.json |  11 +
 tests/qapi-schema/doc-duplicate-features.out  |   0
 tests/qapi-schema/doc-duplicated-arg.err      |   2 +-
 tests/qapi-schema/doc-duplicated-return.err   |   2 +-
 tests/qapi-schema/doc-duplicated-return.json  |   1 +
 tests/qapi-schema/doc-duplicated-since.err    |   2 +-
 tests/qapi-schema/doc-duplicated-since.json   |   1 +
 tests/qapi-schema/doc-empty-arg.err           |   2 +-
 tests/qapi-schema/doc-empty-features.err      |   1 +
 tests/qapi-schema/doc-empty-features.json     |  10 +
 tests/qapi-schema/doc-empty-features.out      |   0
 tests/qapi-schema/doc-empty-section.err       |   2 +-
 tests/qapi-schema/doc-good.json               |  25 +-
 tests/qapi-schema/doc-good.txt                |  21 +-
 tests/qapi-schema/doc-invalid-return.err      |   2 +-
 tests/qapi-schema/doc-invalid-return.json     |   1 +
 tests/qapi-schema/doc-non-first-section.err   |   1 +
 tests/qapi-schema/doc-non-first-section.json  |   6 +
 tests/qapi-schema/doc-non-first-section.out   |   0
 tests/qapi-schema/meson.build                 |  12 +-
 tests/qapi-schema/test-qapi.py                |   2 +-
 58 files changed, 2621 insertions(+), 2628 deletions(-)
 create mode 100644 tests/qapi-schema/doc-duplicate-features.err
 create mode 100644 tests/qapi-schema/doc-duplicate-features.json
 create mode 100644 tests/qapi-schema/doc-duplicate-features.out
 create mode 100644 tests/qapi-schema/doc-empty-features.err
 create mode 100644 tests/qapi-schema/doc-empty-features.json
 create mode 100644 tests/qapi-schema/doc-empty-features.out
 create mode 100644 tests/qapi-schema/doc-non-first-section.err
 create mode 100644 tests/qapi-schema/doc-non-first-section.json
 create mode 100644 tests/qapi-schema/doc-non-first-section.out