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

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> This patch splits the intro/details section for structs which are used
> in an inlinable context; i.e. structs used either as arguments for a
> command/event, or used as a branch of a union. The QAPI documentation
> block for these entities will have their "intro" section removed when
> inlined into other contexts, but may still display the intro section
> on generated documentation *IF* these structs are also used as an
> argument or return type.
>
> Signed-off-by: John Snow <jsnow@redhat.com>

Consider mentioning how this affects rendered documentation now:
MemoryBackendShmProperties and MemoryBackendEpcProperties member
descriptions move up some.

> ---
>  qapi/block-export.json |  5 ++---
>  qapi/crypto.json       |  3 +--
>  qapi/machine.json      | 11 ++++-------
>  qapi/net.json          | 34 +++++++++++++++-------------------
>  qapi/qom.json          |  9 +++------
>  5 files changed, 25 insertions(+), 37 deletions(-)
>
> diff --git a/qapi/block-export.json b/qapi/block-export.json
> index 77459f6321b..e3cee2fb5ce 100644
> --- a/qapi/block-export.json
> +++ b/qapi/block-export.json
> @@ -154,9 +154,8 @@
>  
>  ##
>  # @BlockExportOptionsFuse:
> -#
> -# Options for exporting a block graph node on some (file) mountpoint
> -# as a raw image.
> +#     Options for exporting a block graph node on some (file)
> +#     mountpoint as a raw image.
>  #
>  # Multi-threading note: The FUSE export supports multi-threading.
>  # Currently, requests are distributed across these threads in a
> diff --git a/qapi/crypto.json b/qapi/crypto.json
> index 7b4c80edae2..a8d753d360f 100644
> --- a/qapi/crypto.json
> +++ b/qapi/crypto.json
> @@ -429,8 +429,7 @@
>  
>  ##
>  # @SecretProperties:
> -#
> -# Properties for secret objects.
> +#     Properties for secret objects.
>  #
>  # Either @data or @file must be provided, but not both.
>  #
> diff --git a/qapi/machine.json b/qapi/machine.json
> index b18c6d94a38..1220116bf7d 100644
> --- a/qapi/machine.json
> +++ b/qapi/machine.json
> @@ -684,9 +684,8 @@
>  
>  ##
>  # @NumaHmatLBOptions:
> -#
> -# Set the system locality latency and bandwidth information between
> -# Initiator and Target proximity Domains.
> +#     Set the system locality latency and bandwidth information
> +#     between Initiator and Target proximity Domains.
>  #
>  # For more information about `NumaHmatLBOptions`, see chapter
>  # 5.2.27.4: Table 5-146 of ACPI 6.3 spec.
> @@ -760,8 +759,7 @@
>  
>  ##
>  # @NumaHmatCacheOptions:
> -#
> -# Set the memory side cache information for a given memory domain.
> +#     Set the memory side cache information for a given memory domain.
>  #
>  # For more information of `NumaHmatCacheOptions`, see chapter
>  # 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
> @@ -926,8 +924,7 @@
>  
>  ##
>  # @CpuInstanceProperties:
> -#
> -# Properties identifying a CPU.
> +#     Properties identifying a CPU.
>  #
>  # Which members are optional and which mandatory depends on the
>  # architecture and board.
> diff --git a/qapi/net.json b/qapi/net.json
> index b0a15fd53e2..2a186a71b93 100644
> --- a/qapi/net.json
> +++ b/qapi/net.json
> @@ -719,11 +719,10 @@
>  
>  ##
>  # @NetdevVhostVDPAOptions:
> +#     Vhost-vdpa network backend
>  #
> -# Vhost-vdpa network backend
> -#
> -# vDPA device is a device that uses a datapath which complies with the
> -# virtio specifications with a vendor specific control path.
> +#     vDPA device is a device that uses a datapath which complies with
> +#     the virtio specifications with a vendor specific control path.
>  #

This is an instructive example of a "split or keep in intro" decision
guided by contents: the second paragraph will likely not be useful when
inlined into Netdev, so you keep it in intro.

If the contents of the paragraph would be missed when the inliner elides
it, we'll need to figure out where to put it.  Not now.

>  # @vhostdev: path of vhost-vdpa device (default:'/dev/vhost-vdpa-0')
>  #
> @@ -750,11 +749,10 @@
>  
>  ##
>  # @NetdevVmnetHostOptions:
> +#     vmnet (host mode) network backend.
>  #
> -# vmnet (host mode) network backend.
> -#
> -# Allows the vmnet interface to communicate with other vmnet
> -# interfaces that are in host mode and also with the host.
> +#     Allows the vmnet interface to communicate with other vmnet
> +#     interfaces that are in host mode and also with the host.

Similar.

>  #
>  # @start-address: The starting IPv4 address to use for the interface.
>  #     Must be in the private IP range (RFC 1918).  Must be specified
> @@ -793,15 +791,14 @@
>  
>  ##
>  # @NetdevVmnetSharedOptions:
> +#     vmnet (shared mode) network backend.
>  #
> -# vmnet (shared mode) network backend.
> -#
> -# Allows traffic originating from the vmnet interface to reach the
> -# Internet through a network address translator (NAT).  The vmnet
> -# interface can communicate with the host and with other shared mode
> -# interfaces on the same subnet.  If no DHCP settings, subnet mask and
> -# IPv6 prefix specified, the interface can communicate with any of
> -# other interfaces in shared mode.
> +#     Allows traffic originating from the vmnet interface to reach the
> +#     Internet through a network address translator (NAT).  The vmnet
> +#     interface can communicate with the host and with other shared
> +#     mode interfaces on the same subnet.  If no DHCP settings, subnet
> +#     mask and IPv6 prefix specified, the interface can communicate
> +#     with any of other interfaces in shared mode.

Similar.

>  #
>  # @start-address: The starting IPv4 address to use for the interface.
>  #     Must be in the private IP range (RFC 1918).  Must be specified
> @@ -838,10 +835,9 @@
>  
>  ##
>  # @NetdevVmnetBridgedOptions:
> +#     vmnet (bridged mode) network backend.
>  #
> -# vmnet (bridged mode) network backend.
> -#
> -# Bridges the vmnet interface with a physical network interface.
> +#     Bridges the vmnet interface with a physical network interface.

Similar.

>  #
>  # @ifname: The name of the physical interface to be bridged.
>  #
> diff --git a/qapi/qom.json b/qapi/qom.json
> index 51af9485e6d..e67cd0cd54d 100644
> --- a/qapi/qom.json
> +++ b/qapi/qom.json
> @@ -456,8 +456,7 @@
>  
>  ##
>  # @FilterRedirectorProperties:
> -#
> -# Properties for filter-redirector objects.
> +#     Properties for filter-redirector objects.
>  #
>  # At least one of @indev or @outdev must be present.  If both are
>  # present, they must not refer to the same character device backend.
> @@ -756,8 +755,7 @@
>  
>  ##
>  # @MemoryBackendShmProperties:
> -#
> -# Properties for memory-backend-shm objects.
> +#     Properties for memory-backend-shm objects.
>  #
>  # This memory backend supports only shared memory, which is the
>  # default.
> @@ -771,8 +769,7 @@
>  
>  ##
>  # @MemoryBackendEpcProperties:
> -#
> -# Properties for memory-backend-epc objects.
> +#     Properties for memory-backend-epc objects.
>  #
>  # The @merge boolean option is false by default with epc
>  #