This is RFC quality and mostly meant for Markus to review, but if you're
curious about what we're up to, you're welcome to nose around :)

It's a hackish application of enforcing a strict source section ordering
in QAPIDoc and the accompanying patches that mend the source to respect
that order. The point of the series is to, ultimately, make it easier to
"inject" auto-generated documentation by enforcing a specific order to
sections so that it is easier to insert documentation that is missing or
can be implied from the source. A secondary goal is to more closely
align the source documentation ordering with what gets rendered on the
HTML documentation.

I am sending it to the list in this RFC state mostly to illustrate what
each specific imposition requires in terms of source doc changes, and as
a refresher for the specific restrictions I want to make to facilitate
the inliner feature.

I am not neccessarily married to any specific technique/implementation
for each specific restriction, but if it looks broadly OK to you
(Markus), I can work on any requested polish or corollary cleanups. If
you'd like to see a different approach, that's fine too. We may wish to
discuss the ability to add notes/addendums to sections and what syntax
would support that.

I had originally thought I'd work on the @oob project, but quickly
remembered that my approach to that feature required yet-another place
where we inject a doc section, and decided it would be best if I solved
"where do we inject this autogenerated section?" once and for all,
hence, you are getting this series first.

John Snow (8):
  qapi: differentiate "intro" and "details" sections
  qapi: prohibit 'details' sections between tagged sections
  qapi: add "Details:" disambiguation marker
  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/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 +-
 scripts/qapi/parser.py          | 121 ++++++++++++++++++---
 tests/qapi-schema/doc-good.json |  12 +--
 tests/qapi-schema/doc-good.out  |  10 +-
 tests/qapi-schema/doc-good.txt  |  18 ++--
 35 files changed, 695 insertions(+), 530 deletions(-)

-- 
2.53.0