Re: [PATCH] block/export: fix QAPI doc indentation style violation

[Peter Maydell]

On Thu, 1 Oct 2020 at 14:18, Stefan Hajnoczi <stefanha@redhat.com> wrote:
>
> Since commit a69a6d4b4d4fae2e3d2506241e22a78ff1732283
> ("scripts/qapi/parser.py: improve doc comment indent handling") the QAPI
> generator emits an error when unindented text follows "Returns:".

> -# @addr: Address on which to listen.
> -# @tls-creds: ID of the TLS credentials object (since 2.6).
> -# @tls-authz: ID of the QAuthZ authorization object used to validate
> -#             the client's x509 distinguished name. This object is
> -#             is only resolved at time of use, so can be deleted and
> -#             recreated on the fly while the NBD server is active.
> -#             If missing, it will default to denying access (since 4.0).
> -# @max-connections: The maximum number of connections to allow at the same
> -#                   time, 0 for unlimited. (since 5.2; default: 0)
> -#
> -# Returns: error if the server is already running.
> -#
>  # Keep this type consistent with the NbdServerOptions type. The only intended
>  # difference is using SocketAddressLegacy instead of SocketAddress.

Note that the reason why the generator complains is because
according to the doc-comment structure this paragraph
("Keep this type...") is actually part of the Returns: section.
This is the same as it has always been; it's just that now the
generator wants the indent to match the structure.

Given the contents of the paragraph, it clearly wasn't intentional
that it be part of the Returns: section, so moving the text is
the right thing.

thanks
-- PMM