Re: [PATCH 1/6] qapi: convert remaining simple intros for block-export.json

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> These are either structs or unions that are used in an inlinable
> context: i.e. the generated documentation is likely to feature a
> version of this documentation block that does not include the intro in
> context of another command, event, or structure.
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qapi/block-export.json | 19 ++++++++-----------
>  1 file changed, 8 insertions(+), 11 deletions(-)
>
> diff --git a/qapi/block-export.json b/qapi/block-export.json
> index 2893c6456d5..e9f7e72c8ee 100644
> --- a/qapi/block-export.json
> +++ b/qapi/block-export.json
> @@ -37,10 +37,9 @@
>  
>  ##
>  # @NbdServerOptions:
> -#
> -# Keep this type consistent with the `NbdServerOptionsLegacy` type.
> -# The only intended difference is using `SocketAddress` instead of
> -# `SocketAddressLegacy`.
> +#     Keep this type consistent with the `NbdServerOptionsLegacy`
> +#     type.  The only intended difference is using `SocketAddress`
> +#     instead of `SocketAddressLegacy`.

"Keep this consistent" is for developers, and should not go into user
reference documentation.

Let's leave this for another day, just take note of future work:

6. Move comments for developers out of doc comments

>  #
>  # @addr: Address on which to listen (since 4.2).
>  ##
> @@ -50,10 +49,9 @@
>  
>  ##
>  # @NbdServerOptionsLegacy:
> -#
> -# Keep this type consistent with the `NbdServerOptions` type.  The
> -# only intended difference is using `SocketAddressLegacy` instead of
> -# `SocketAddress`.
> +#     Keep this type consistent with the `NbdServerOptions` type.  The
> +#     only intended difference is using `SocketAddressLegacy` instead
> +#     of `SocketAddress`.

Likewise.

>  #
>  # @addr: Address on which to listen (since 1.3).
>  ##
> @@ -339,9 +337,8 @@
>  
>  ##
>  # @BlockExportOptions:
> -#
> -# Describes a block export, i.e. how single node should be exported on
> -# an external interface.
> +#     Describes a block export, i.e. how single node should be
> +#     exported on an external interface.
>  #
>  # @type: Block export type
>  #