Skip to content

qapi: enforce section ordering

John Snow qemu-devel 2 versions – In review

Get series with b4
b4 am [email protected]

Versions newest first · linked by author and title

  1. v2 Latest10 patches 1 replyIn review
  2. 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 filesSizeRepliesApplied
1/10qapi: differentiate "intro" and "details" sectionsdocs/sphinx/qapidoc.py scripts/qapi/parser.py tests/qapi-schema/doc-good.out+29 -160 replies
2/10qapi: prohibit 'details' sections between tagged sectionsdocs/devel/qapi-code-gen.rst qapi/qom.json scripts/qapi/parser.py +7 more+55 -140 replies
3/10qapi: add "Details:" disambiguation markerdocs/devel/qapi-code-gen.rst qapi/machine.json qapi/migration.json +3 more+31 -50 replies
4/10qapi: add "Details:" markers where neededqapi/block-core.json qapi/machine.json qapi/misc-arm.json +3 more+15 -00 replies
5/10qapi: add "Details:" markers where potentially neededqapi/migration.json+4 -00 replies
6/10qapi: detect potentially semantically ambiguous intro paragraphsscripts/qapi/parser.py tests/qapi-schema/doc-missing-details.err tests/qapi-schema/doc-missing-details.json +2 more+64 -00 replies
7/10qapi: re-order QAPI doc block sectionsqapi/accelerator.json qapi/block-core.json qapi/block-export.json +8 more+100 -1000 replies
8/10qapi: enforce doc block section orderingscripts/qapi/parser.py+34 -210 replies
9/10qapi: re-order 'since' sections to always be lastdocs/interop/firmware.json docs/interop/vhost-user.json qapi/accelerator.json +25 more+472 -3830 replies
10/10qapi: enforce strict positioning for "Since:" sectionscripts/qapi/parser.py+1 -10 replies

Reviews trailers per patch

No Reviewed-by, Acked-by or Tested-by trailers for v2 yet.

Read the v2 thread

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