John Snow <[email protected]> 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 <[email protected]>
[...]
> 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.
[...]
