qapi: enforce section ordering
Get series with b4
b4 am [email protected]Versions newest first · linked by author and title
- v2 Latest10 patches 1 replyIn review
- v18 patches 20 repliesSuperseded
Changes in v2 from the cover letter
- Add quite a few FIXME stubs for tests
- Much more carefully delineate QAPI source changes into ones required to prevent visible changes, and ones that explictly create visible changes
- Various commit message / comment changes
- Fix heuristic for griping about Intro/Details "ambiguity" to also ignore generated "Returns" sections, which was missing before and missed quite a few cases that did impact rendered output
Patches in v2 No applies recorded yet
| # | Subject and files | Size | Replies | Applied |
|---|---|---|---|---|
| 1/10 | qapi: differentiate "intro" and "details" sectionsdocs/ scripts/ tests/ | +29 | 0 replies | |
| 2/10 | qapi: prohibit 'details' sections between tagged sectionsdocs/ qapi/ scripts/ +7 more | +55 | 0 replies | |
| 3/10 | qapi: add "Details:" disambiguation markerdocs/ qapi/ qapi/ +3 more | +31 | 0 replies | |
| 4/10 | qapi: add "Details:" markers where neededqapi/ qapi/ qapi/ +3 more | +15 | 0 replies | |
| 5/10 | qapi: add "Details:" markers where potentially neededqapi/ | +4 | 0 replies | |
| 6/10 | qapi: detect potentially semantically ambiguous intro paragraphsscripts/ tests/ tests/ +2 more | +64 | 0 replies | |
| 7/10 | qapi: re-order QAPI doc block sectionsqapi/ qapi/ qapi/ +8 more | +100 | 0 replies | |
| 8/10 | qapi: enforce doc block section orderingscripts/ | +34 | 0 replies | |
| 9/10 | qapi: re-order 'since' sections to always be lastdocs/ docs/ qapi/ +25 more | +472 | 0 replies | |
| 10/10 | qapi: enforce strict positioning for "Since:" sectionscripts/ | +1 | 0 replies |
Reviews trailers per patch
No Reviewed-by, Acked-by or Tested-by trailers for v2 yet.
Cover letter [PATCH v2 00/10] qapi: enforce section ordering
Hiya, this series is meant to accomplish mostly one thing: Enforce a stricter ordering of sections in QAPI documentation blocks.
The reason to do this is mostly for the sake of the inliner: if QAPI documentation blocks have some known, canonical order, it is easier to merge two documentation blocks together for the purposes of showing all arguments for commands/etc in a simple, flat list without needing to follow hyperlink breadcrumbs.
Another reason to do this is to simplify where we insert autogenerated documentation. If the order is enforced, then inserting "Not Documented" stubs for members and generated "Returns:" statements can have a much simpler algorithm that will always match how manually written documentation is presented, in the same order.
This is still pretty RFC quality, the tests have not been implemented and the implementation of changes in the parser are still pretty fuzzy. The main point of this series at this point in time is to review the QAPI source changes and decide if the strategy employed in fixing the section ordering is the direction we ultimately want to go in.
V2:
- Add quite a few FIXME stubs for tests
- Much more carefully delineate QAPI source changes into ones required to prevent visible changes, and ones that explictly create visible changes
- Various commit message / comment changes
- Fix heuristic for griping about Intro/Details "ambiguity" to also ignore generated "Returns" sections, which was missing before and missed quite a few cases that did impact rendered output
To verify rendering changes (or lack thereof), I used this strategy:
(1) For a reference output before a change, I ran a build:
Quoted 1 line
V=1 DEBUG=1 make -j13;
(2) Then I created some reference output for the intermediate rST debugging output files (fish syntax):
> for i in *.ir; sed -E 's|\.json:[0-9]{4}|.json:nnnn|g' $i > $i.ref; end
(3) Then after applying a patch, to check for any differences, I re-ran the build as in (1) and then:
> for i in *.ir; sed -E 's|\.json:[0-9]{4}|.json:nnnn|g' $i > $i.new; end > for i in *.ir; meld $i.ref $i.new; end
An observation: Most of the time, the Intro section is only one paragraph anyway. We might be able to save on some explicit "Details:" syntax if we just formalize the idea that the intro can only ever be at most one paragraph. I don't know if we want to do that (Do we want to keep the ability to run long in the "intro"?) - but it would cut down on quite a lot of markup that this series adds.
John Snow (10):
qapi: differentiate "intro" and "details" sections
qapi: prohibit 'details' sections between tagged sections
qapi: add "Details:" disambiguation marker
qapi: add "Details:" markers where needed
qapi: add "Details:" markers where potentially needed
qapi: detect potentially semantically ambiguous intro paragraphs
qapi: re-order QAPI doc block sections
qapi: enforce doc block section ordering
qapi: re-order 'since' sections to always be last
qapi: enforce strict positioning for "Since:" section
docs/devel/qapi-code-gen.rst | 33 +++- docs/interop/firmware.json | 4 +- docs/interop/vhost-user.json | 3 +- docs/sphinx/qapidoc.py | 2 +- qapi/accelerator.json | 12 +- qapi/acpi.json | 8 +- qapi/block-core.json | 183 ++++++++++--------- qapi/block-export.json | 20 +- qapi/block.json | 48 ++--- qapi/char.json | 36 ++-- qapi/control.json | 14 +- qapi/dump.json | 16 +- qapi/machine-s390x.json | 16 +- qapi/machine.json | 144 ++++++++------- qapi/migration.json | 102 ++++++----- qapi/misc-arm.json | 6 +- qapi/misc-i386.json | 40 ++-- qapi/misc.json | 68 ++++--- qapi/net.json | 42 ++--- qapi/pci.json | 4 +- qapi/qdev.json | 12 +- qapi/qom.json | 34 ++-- qapi/replay.json | 16 +- qapi/rocker.json | 16 +- qapi/run-state.json | 66 ++++--- qapi/tpm.json | 12 +- qapi/trace.json | 8 +- qapi/transaction.json | 4 +- qapi/ui.json | 76 ++++---- qapi/vfio.json | 4 +- qapi/virtio.json | 46 ++--- qapi/yank.json | 2 +- qga/qapi-schema.json | 2 + scripts/qapi/parser.py | 134 ++++++++++++-- tests/qapi-schema/doc-good.json | 12 +- tests/qapi-schema/doc-good.out | 10 +- tests/qapi-schema/doc-good.txt | 18 +- tests/qapi-schema/doc-misplaced-details.err | 0 tests/qapi-schema/doc-misplaced-details.json | 3 + tests/qapi-schema/doc-misplaced-details.out | 11 ++ tests/qapi-schema/doc-missing-details.err | 0 tests/qapi-schema/doc-missing-details.json | 3 + tests/qapi-schema/doc-missing-details.out | 11 ++ tests/qapi-schema/meson.build | 2 + 44 files changed, 784 insertions(+), 519 deletions(-) create mode 100644 tests/qapi-schema/doc-misplaced-details.err create mode 100644 tests/qapi-schema/doc-misplaced-details.json create mode 100644 tests/qapi-schema/doc-misplaced-details.out create mode 100644 tests/qapi-schema/doc-missing-details.err create mode 100644 tests/qapi-schema/doc-missing-details.json create mode 100644 tests/qapi-schema/doc-missing-details.out
Signature · 1 line
2.53.0