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

-- 
2.53.0