On Thu, 1 Oct 2020 at 14:18, Stefan Hajnoczi <stefa...@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
