Re: [PATCH v2 09/10] qapi: split intro sections for data structs

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> The structs of concern in this patch are those for which no other QAPI
> definition uses as a data type to describe its own arguments or as a
> branch of a union: i.e. they are not currently inlined and as such the
> precise semantics of their intro/details split is *currently* of less
> concern.
>
> Of course, they could be inlined in the future, so the semantics of
> this split are still worth investigating.
>
> Review notes: Similar notes as previous patches in this series with
> respect to how splits were determined, and why details were not
> physically relocated.

Help me out, please: which notes exactly?

> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qapi/acpi.json       | 3 +--
>  qapi/block-core.json | 5 ++---
>  qapi/compat.json     | 3 +--
>  qapi/machine.json    | 9 ++++-----
>  4 files changed, 8 insertions(+), 12 deletions(-)
>
> diff --git a/qapi/acpi.json b/qapi/acpi.json
> index 291a04a7ea4..82e82d7cf89 100644
> --- a/qapi/acpi.json
> +++ b/qapi/acpi.json
> @@ -13,8 +13,7 @@
>  
>  ##
>  # @AcpiTableOptions:
> -#
> -# Specify an ACPI table on the command line to load.
> +#     Specify an ACPI table on the command line to load.
>  #
>  # At most one of @file and @data can be specified.  The list of files
>  # specified by any one of them is loaded and concatenated in order.
> diff --git a/qapi/block-core.json b/qapi/block-core.json
> index 13981d7e69d..741c8165c06 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
> @@ -843,9 +843,8 @@
>  
>  ##
>  # @BlockMeasureInfo:
> -#
> -# Image file size calculation information.  This structure describes
> -# the size requirements for creating a new image file.
> +#     Image file size calculation information.  This structure
> +#     describes the size requirements for creating a new image file.
>  #
>  # The size requirements depend on the new image file format.  File
>  # size always equals virtual disk size for the 'raw' format, even for
> diff --git a/qapi/compat.json b/qapi/compat.json
> index ef1853b9acd..b42d142ddcc 100644
> --- a/qapi/compat.json
> +++ b/qapi/compat.json
> @@ -37,8 +37,7 @@
>  
>  ##
>  # @CompatPolicy:
> -#
> -# Policy for handling deprecated management interfaces.
> +#     Policy for handling deprecated management interfaces.
>  #
>  # This is intended for testing users of the management interfaces.
>  #
   # Limitation: covers only syntactic aspects of QMP, i.e. stuff tagged
   # with feature 'deprecated' or 'unstable'.  We may want to extend it
   # to cover semantic aspects and CLI.
   #
   # Limitation: deprecated-output policy @hide is not implemented for
   # enumeration values.  They behave the same as with policy @accept.

"This is intended for" caught my eyes.  Inlining it feels problematic.
For starters, how will "this" be interpreted in the new context?

Fortunately, this won't be inlined any time soon: it's used just as
argument of -compat, and the CLI isn't QAPIfied.

Similar difficulties can arise whenever we inline more than just member
descriptions.  Avoiding them now feels impractical; we'll have to read
the texts in the contexts where the inliner puts them.  I see a lot of
proofreading and doc editing in our future.

> diff --git a/qapi/machine.json b/qapi/machine.json
> index 00a03e57b98..b18c6d94a38 100644
> --- a/qapi/machine.json
> +++ b/qapi/machine.json
> @@ -1629,9 +1629,9 @@
>  
>  ##
>  # @SMPConfiguration:
> -#
> -# Schema for CPU topology configuration.  A missing value lets QEMU
> -# figure out a suitable value based on the ones that are provided.
> +#     Schema for CPU topology configuration.  A missing value lets
> +#     QEMU figure out a suitable value based on the ones that are
> +#     provided.
>  #
>  # The members other than @cpus and @maxcpus define a topology of
>  # containers.
> @@ -1890,8 +1890,7 @@
>  
>  ##
>  # @CpuModelInfo:
> -#
> -# Virtual CPU model.
> +#     Virtual CPU model.
>  #
>  # A CPU model consists of the name of a CPU definition, to which delta
>  # changes are applied (e.g. features added/removed).  Most magic