Hello, this work converts "simple" intro sections for data struct definitions (and one alternate) in the QAPI schema to use the new syntax. This is part of our ongoing effort to add the mythical "inliner" to our generated QMP documentation.
"simple" here is a non-technical distinction that means a single paragraph of text followed by an existing section boundary that naturally already delineates what comprises the intro. (This is about 25% of the remaining conversions.) "data struct" is another non-technical distinction that means a QAPI struct that is not used as a branch, argument definition, or the basis of another struct. In effect, it is only "data" and as a result, is not *currently* a candidate to be inlined into any other definition. Documentation that is to be "inlined"-- to be written into another definition's documentation-- needs to ensure that the documentation written in the "intro" segment is not crucial to understanding the behavior of the individual members. The "intro" does not get inlined, but the rest of the documentation does. These "data structs" as isolated in this series currently are not eligible to be inlined. As such, the precise distinction between intro and details for these definitions is not presently as crucial - however, these structs may become inlined in the future, so a closer eye is still warranted. If you are a non-QAPI maintainer who has been CC'd on this series, you may wish to review what information is being counted as the "intro" (The indented paragraph) and keep in mind that in the future, this text may not be visible to the end-user reading our QMP documentation if this structure is utilized as the 'base' for another struct, used as the arguments for a command or event, or used as branch of a union. This series keeps it pretty simple, and every conversion herein is being codified as "the intro", i.e. "not crucial to understanding the behavior of the members of this struct". John Snow (10): qapi: convert simple data struct intros for uefi.json qapi: convert simple data struct intros for misc-arm.json qapi: convert simple data struct intros for acpi.json qapi: convert simple data struct intros for run-state.json qapi: convert simple data struct intros for yank.json qapi: convert simple data struct intros for cxl.json qapi: convert simple data struct intros for virtio.json qapi: convert simple data struct intros for machine.json qapi: convert simple data struct intros for block-core.json qapi: convert simple alternate intros for common.json qapi/acpi.json | 7 +++---- qapi/block-core.json | 37 ++++++++++++++++--------------------- qapi/common.json | 7 +++---- qapi/cxl.json | 7 +++---- qapi/machine.json | 12 +++++------- qapi/misc-arm.json | 9 ++++----- qapi/run-state.json | 7 +++---- qapi/uefi.json | 5 ++--- qapi/virtio.json | 37 ++++++++++++++++--------------------- qapi/yank.json | 10 ++++------ 10 files changed, 59 insertions(+), 79 deletions(-) -- 2.55.0
