Re: [PATCH v4 7/7] qapi: convert intro sections followed by notes/examples

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> These provide a rather natural cutoff point, but technically this does
> introduce a new intro/details split to these documentation blocks.

Not sure what you mean by "technically".

>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qapi/machine.json   |  5 ++---
>  qapi/migration.json | 15 +++++++--------
>  qapi/misc.json      |  3 +--
>  qapi/run-state.json |  7 +++----
>  4 files changed, 13 insertions(+), 17 deletions(-)
>
> diff --git a/qapi/machine.json b/qapi/machine.json
> index 84d95c8d87f..276258d9e5c 100644
> --- a/qapi/machine.json
> +++ b/qapi/machine.json
> @@ -1209,9 +1209,8 @@
>  
>  ##
>  # @HV_BALLOON_STATUS_REPORT:
> -#
> -# Emitted when the hv-balloon driver receives a "STATUS" message from
> -# the guest.
> +#     Emitted when the hv-balloon driver receives a "STATUS" message
> +#     from the guest.
>  #
>  # .. note:: This event is rate-limited.
>  #
   # Since: 8.2

The patch splits the first section between after the first paragraph,
i.e. before the note.

This matters, because we insert generated argument documentation after
the first section.  Rendered documentation changes like this

    Emitted when the hv-balloon driver receives a "STATUS" message from
    the guest.
 
+   Members:
+      * The members of "HvBalloonInfo".
+
    Note:
 
      This event is rate-limited.
 
-   Members:
-      * The members of "HvBalloonInfo".
-
    Example::
 
       <- { "event": "HV_BALLOON_STATUS_REPORT",

> diff --git a/qapi/migration.json b/qapi/migration.json
> index d571c06fc20..a272e701385 100644
> --- a/qapi/migration.json
> +++ b/qapi/migration.json
> @@ -1254,10 +1254,10 @@
>  
>  ##
>  # @migrate_cancel:
> -#
> -# Cancel the currently executing migration process.  Allows a new
> -# migration to be started right after.  When postcopy-ram is in use,
> -# cancelling is not allowed after the postcopy phase has started.
> +#     Cancel the currently executing migration process.  Allows a new
> +#     migration to be started right after.  When postcopy-ram is in
> +#     use, cancelling is not allowed after the postcopy phase has
> +#     started.
>  #
>  # .. note:: This command succeeds even if there is no migration
>  #    process running.

Similar split, but rendered documentation doesn't change, because
nothing gets inserted.

Same for the remaining hunks.

Should the one hunk that changes rendered documentation be in the "qapi:
convert/split remaining QAPI/QMP intro sections" series?

[...]