Re: [PATCH 7/8] qapi: re-order 'since' sections to always be last

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> Note that with "Since" being moved to the last position, we open up a
> good many new cases of ambiguos intro-vs-details text which must be
> corrected with "Details:" tags.
>
> This patch doesn't only add these markers where it would definitively
> impact inlining - it adds them to *any* doc block that has more than one
> paragraph of plaintext and no other distinguishing features (members,
> features, errors, returns).
>
> It may well be the case that not every last one of these *needs* to be
> amended in this way, but this is the broad coverage shotgun approach
> that demonstrates which places in the code may cause footguns with
> regards to automated stub insertions of members/arguments/etc, returns,
> or inlining order ambiguities.
>
> Signed-off-by: John Snow <jsnow@redhat.com>

[...]

> diff --git a/qapi/accelerator.json b/qapi/accelerator.json
> index d333a772384..5624b5d88b7 100644
> --- a/qapi/accelerator.json
> +++ b/qapi/accelerator.json
> @@ -29,12 +29,12 @@
>  #
>  # Return information about KVM acceleration
>  #
> -# Since: 0.14
> -#
>  # .. qmp-example::
>  #
>  #     -> { "execute": "query-kvm" }
>  #     <- { "return": { "enabled": true, "present": true } }
> +#
> +# Since: 0.14
>  ##
>  { 'command': 'query-kvm', 'returns': 'KvmInfo' }
>  

Rendered output changes unexpectedly from

    Command query-kvm (Since: 0.14)

       Return information about KVM acceleration

       Return:
          KvmInfo

       Example::

          -> { "execute": "query-kvm" }
          <- { "return": { "enabled": true, "present": true } }

to

    Command query-kvm (Since: 0.14)

       Return information about KVM acceleration

       Example::

          -> { "execute": "query-kvm" }
          <- { "return": { "enabled": true, "present": true } }

       Return:
          KvmInfo

I guess the "Since:" quietly serves as separator between INTRO and
DETAILS before the patch, and the patch is missing a DETAILS: line.

Several more instances follow.

[...]