Skip to content

qapi: convert (very) trivial intro sections

John Snow linux-cxl linux-edac qemu-devel qemu-trivial 4 versions – In review

Get series with b4
b4 am [email protected]

Versions newest first · linked by author and title

  1. v4 Latest43 patches 5 repliesIn review
  2. v343 patches 19 repliesSuperseded
  3. v244 patches 20 repliesSuperseded
Earlier versions · 1
VersionPostedPatchesRepliesStatus
v114 patches7 repliesSuperseded

Changes in v4 from the cover letter

- Added r-b's from various folks
- Dropped a few conversion cases that were just simply not trivial enough.

Patches in v4 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/43qapi: convert trivial intro sections for error.jsonqapi/error.json+1 -20 replies
2/43qapi: convert trivial intro sections for acpi-hest.jsonqapi/acpi-hest.json+2 -20 replies
3/43qapi: convert trivial intro sections for ebpf.jsonqapi/ebpf.json+2 -40 replies
4/43qapi: convert trivial intro sections for compat.jsonqapi/compat.json+2 -40 replies
5/43qapi: convert trivial intro sections for vfio.jsonqapi/vfio.json+2 -20 replies
6/43qapi: convert trivial intro sections for trace.jsonqapi/trace.json+4 -80 replies
7/43qapi: convert trivial intro sections for misc-arm.jsonqapi/misc-arm.json+2 -40 replies
8/43qapi: convert trivial intro sections for cryptodev.jsonqapi/cryptodev.json+6 -120 replies
9/43qapi: convert trivial intro sections for machine-common.jsonqapi/machine-common.json+5 -90 replies
10/43qapi: convert trivial intro sections for accelerator.jsonqapi/accelerator.json+6 -120 replies
11/43qapi: convert trivial intro sections for authz.jsonqapi/authz.json+7 -140 replies
12/43qapi: convert trivial intro sections for yank.jsonqapi/yank.json+2 -30 replies
13/43qapi: convert trivial intro sections for replay.jsonqapi/replay.json+2 -40 replies
14/43qapi: convert trivial intro sections for machine-s390x.jsonqapi/machine-s390x.json+5 -80 replies
15/43qapi: convert trivial intro sections for acpi.jsonqapi/acpi.json+3 -50 replies
16/43qapi: convert trivial intro sections for tpm.jsonqapi/tpm.json+10 -190 replies
17/43qapi: convert trivial intro sections for qdev.jsonqapi/qdev.json+5 -90 replies
18/43qapi: convert trivial intro sections for control.jsonqapi/control.json+11 -190 replies
19/43qapi: convert trivial intro sections for dump.jsonqapi/dump.json+7 -120 replies
20/43qapi: convert trivial intro sections for common.jsonqapi/common.json+10 -190 replies
21/43qapi: convert trivial intro sections for sockets.jsonqapi/sockets.json+12 -190 replies
22/43qapi: convert trivial intro sections for transaction.jsonqapi/transaction.json+5 -90 replies
23/43qapi: convert trivial intro sections for stats.jsonqapi/stats.json+13 -210 replies
24/43qapi: convert trivial intro sections for job.jsonqapi/job.json+6 -120 replies
25/43qapi: convert trivial intro sections for pci.jsonqapi/pci.json+9 -180 replies
26/43qapi: convert trivial intro sections for introspect.jsonqapi/introspect.json+14 -260 replies
27/43qapi: convert trivial intro sections for rocker.jsonqapi/rocker.json+13 -260 replies
28/43qapi: convert trivial intro sections for misc-i386.jsonqapi/misc-i386.json+18 -340 replies
29/43qapi: convert trivial intro sections for block-export.jsonqapi/block-export.json+18 -320 replies
30/43qapi: convert trivial intro sections for audio.jsonqapi/audio.json+32 -560 replies
31/43qapi: convert trivial intro sections for block.jsonqapi/block.json+17 -240 replies
32/43qapi: convert trivial intro sections for misc.jsonqapi/misc.json+27 -470 replies
33/43qapi: convert trivial intro sections for crypto.jsonqapi/crypto.json+36 -640 replies
34/43qapi: convert trivial intro sections for cxl.jsonqapi/cxl.json+2 -40 replies
35/43qapi: convert trivial intro sections for run-state.jsonqapi/run-state.json+42 -710 replies
36/43qapi: convert trivial intro sections for char.jsonqapi/char.json+30 -600 replies
37/43qapi: convert trivial intro sections for virtio.jsonqapi/virtio.json+20 -340 replies
38/43qapi: convert trivial intro sections for net.jsonqapi/net.json+33 -590 replies
39/43qapi: convert trivial intro sections for qom.jsonqapi/qom.json+51 -990 replies
40/43qapi: convert trivial intro sections for ui.jsonqapi/ui.json+68 -1310 replies
41/43qapi: convert trivial intro sections for migration.jsonqapi/migration.json+48 -830 replies
42/43qapi: convert trivial intro sections for machine.jsonqapi/machine.json+68 -1270 replies
43/43qapi: convert trivial intro sections for block-core.jsonqapi/block-core.json+157 -2740 replies

Reviews trailers per patch

7 of 43 patches have a Reviewed-by or Acked-by of their own; the series has one for all of them.

PatchPhilippe Mathieu-DaudéCédric Le GoaterMarkus Armbruster
SeriesR-b
1/43R-b
2/43
3/43
4/43
5/43R-b
6/43
7/43
8/43
9/43
10/43R-b
11/43
12/43
13/43
14/43
15/43
16/43
17/43R-b
18/43
19/43
20/43
21/43
22/43
23/43
24/43
25/43R-b
26/43
27/43
28/43
29/43
30/43
31/43
32/43
33/43
34/43
35/43R-b
36/43
37/43
38/43
39/43R-b
40/43
41/43
42/43
43/43

Trailers given in replies are filled; those carried in the patches from earlier versions are outlined with dashes. Scroll the table sideways for all 3 reviewers.

Read the v4 thread

Cover letter [PATCH v4 00/43] qapi: convert (very) trivial intro sections

v4:
- Added r-b's from various folks
- Dropped a few conversion cases that were just simply not trivial enough.

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.

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.

-

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     | 431 ++++++++++++++-------------------------
 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        | 195 ++++++------------
 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, 833 insertions(+), 1501 deletions(-)
Signature · 1 line
2.55.0