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 -- 2.43.0
