v3:
As per Markus' request, the intro section conversion has been split
even further into the *very* trivial; leaving the semi-trivial and
not-trivial conversions for later consideration.
If you are a non-qapi/non-docs maintainer being CC'd on this patch,
there is **very likely** nothing for you to do here; we are only
changing spacing and syntax, but not modifying content in any way
in this series in particular. Please feel free to mark-as-read and
move on with your day.
-
Hi, this patchset converts trivial "introductory" sections in the QAPI
documentation to use the new, explicit intro section syntax.
This is being done primarily for the benefit of the forthcoming
"inliner", a feature for the rendered HTML QMP documentation that
seeks to "inline" QMP command argument documentation into the argument
list for each command.
There are two main motives here:
(1) We want the split between the "introduction" and "details"
sections to be mechanically obvious, so that auto-generated or
inlined documentation has a well-defined, obvious spot to go.
(2) We do not want to inline irrelevant, introductory text describing
structures to be copied into command documentation.
This patchset tackles "very trivial" conversions: cases where the
existing leading plaintext is only a single sentence and is
immediately followed by a tagged section, the end of the documentation
block, or some other pre-existing syntactical delineation. (i.e.: not
more plaintext.)
NOTE: This series *may* miss some conversions; future QAPI changes will
enforce the new syntax and any cases that have appeared since v1 will
be identified and corrected at that time; we are concerned with the
bulk and ease-of-review here, not completeness. This is precisely why
the new intro syntax and parser were carefully designed to allow
gradual conversion.
NOTE2: Future patches that may require more scrutiny will handle the
remaining conversions - There are some very subtle concerns that are
not readily apparent in the very minor textual changes that will be
spelled out for reviewers in the cover letters for those series.
This is enough for today, don't you think?
John Snow (43):
qapi: convert trivial intro sections for error.json
qapi: convert trivial intro sections for acpi-hest.json
qapi: convert trivial intro sections for ebpf.json
qapi: convert trivial intro sections for compat.json
qapi: convert trivial intro sections for vfio.json
qapi: convert trivial intro sections for trace.json
qapi: convert trivial intro sections for misc-arm.json
qapi: convert trivial intro sections for cryptodev.json
qapi: convert trivial intro sections for machine-common.json
qapi: convert trivial intro sections for accelerator.json
qapi: convert trivial intro sections for authz.json
qapi: convert trivial intro sections for yank.json
qapi: convert trivial intro sections for replay.json
qapi: convert trivial intro sections for machine-s390x.json
qapi: convert trivial intro sections for acpi.json
qapi: convert trivial intro sections for tpm.json
qapi: convert trivial intro sections for qdev.json
qapi: convert trivial intro sections for control.json
qapi: convert trivial intro sections for dump.json
qapi: convert trivial intro sections for common.json
qapi: convert trivial intro sections for sockets.json
qapi: convert trivial intro sections for transaction.json
qapi: convert trivial intro sections for stats.json
qapi: convert trivial intro sections for job.json
qapi: convert trivial intro sections for pci.json
qapi: convert trivial intro sections for introspect.json
qapi: convert trivial intro sections for rocker.json
qapi: convert trivial intro sections for misc-i386.json
qapi: convert trivial intro sections for block-export.json
qapi: convert trivial intro sections for audio.json
qapi: convert trivial intro sections for block.json
qapi: convert trivial intro sections for misc.json
qapi: convert trivial intro sections for crypto.json
qapi: convert trivial intro sections for cxl.json
qapi: convert trivial intro sections for run-state.json
qapi: convert trivial intro sections for char.json
qapi: convert trivial intro sections for virtio.json
qapi: convert trivial intro sections for net.json
qapi: convert trivial intro sections for qom.json
qapi: convert trivial intro sections for ui.json
qapi: convert trivial intro sections for migration.json
qapi: convert trivial intro sections for machine.json
qapi: convert trivial intro sections for block-core.json
qapi/accelerator.json | 18 +-
qapi/acpi-hest.json | 4 +-
qapi/acpi.json | 8 +-
qapi/audio.json | 88 +++-----
qapi/authz.json | 21 +-
qapi/block-core.json | 448 ++++++++++++++-------------------------
qapi/block-export.json | 50 ++---
qapi/block.json | 41 ++--
qapi/char.json | 90 +++-----
qapi/common.json | 29 +--
qapi/compat.json | 6 +-
qapi/control.json | 30 +--
qapi/crypto.json | 100 ++++-----
qapi/cryptodev.json | 18 +-
qapi/cxl.json | 6 +-
qapi/dump.json | 19 +-
qapi/ebpf.json | 6 +-
qapi/error.json | 3 +-
qapi/introspect.json | 40 ++--
qapi/job.json | 18 +-
qapi/machine-common.json | 14 +-
qapi/machine-s390x.json | 13 +-
qapi/machine.json | 208 +++++++-----------
qapi/migration.json | 131 +++++-------
qapi/misc-arm.json | 6 +-
qapi/misc-i386.json | 52 ++---
qapi/misc.json | 74 +++----
qapi/net.json | 92 +++-----
qapi/pci.json | 27 +--
qapi/qdev.json | 14 +-
qapi/qom.json | 150 +++++--------
qapi/replay.json | 6 +-
qapi/rocker.json | 39 ++--
qapi/run-state.json | 113 ++++------
qapi/sockets.json | 31 ++-
qapi/stats.json | 34 ++-
qapi/tpm.json | 29 +--
qapi/trace.json | 12 +-
qapi/transaction.json | 14 +-
qapi/ui.json | 199 ++++++-----------
qapi/vfio.json | 4 +-
qapi/virtio.json | 54 ++---
qapi/yank.json | 5 +-
43 files changed, 845 insertions(+), 1519 deletions(-)
--
2.55.0
