Re: [Qemu-devel] [PATCH v5 09/17] qapi: add some sections in docs

[Markus Armbruster <armbru@redhat.com>]

Second thoughts...

Marc-André Lureau <marcandre.lureau@redhat.com> writes:

> Add some more section titles to organize the produced documents.
>
> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> ---
>  qapi-schema.json     |  4 ++++
>  qapi/block-core.json |  6 ++++--
>  qapi/block.json      | 10 ++++++++--
>  qapi/common.json     |  6 ++++--
>  qapi/crypto.json     |  5 ++++-
>  qapi/event.json      |  6 ++++++
>  qapi/rocker.json     |  4 ++++
>  qapi/trace.json      |  3 +++
>  8 files changed, 37 insertions(+), 7 deletions(-)
>
> diff --git a/qapi-schema.json b/qapi-schema.json
> index dfe68ba..69340f2 100644
> --- a/qapi-schema.json
> +++ b/qapi-schema.json
> @@ -20,6 +20,10 @@
>  # QAPI introspection
>  { 'include': 'qapi/introspect.json' }
>  
> +##
> +# = QMP commands
> +##
> +
>  ##
>  # @qmp_capabilities:
>  #
> diff --git a/qapi/block-core.json b/qapi/block-core.json
> index ec1da2a..05cedc3 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
> @@ -1,6 +1,8 @@
>  # -*- Mode: Python -*-
> -#
> -# QAPI block core definitions (vm unrelated)
> +
> +##
> +# == QAPI block core definitions (vm unrelated)
> +##
>  
>  # QAPI common definitions
>  { 'include': 'common.json' }
> diff --git a/qapi/block.json b/qapi/block.json
> index 937df05..e4ad74b 100644
> --- a/qapi/block.json
> +++ b/qapi/block.json
> @@ -1,10 +1,16 @@
>  # -*- Mode: Python -*-
> -#
> -# QAPI block definitions (vm related)
> +
> +##
> +# = QAPI block definitions
> +##
>  
>  # QAPI block core definitions
>  { 'include': 'block-core.json' }
>  
> +##
> +# == QAPI block definitions (vm unrelated)
> +##
> +
>  ##
>  # @BiosAtaTranslation:
>  #
> diff --git a/qapi/common.json b/qapi/common.json
> index 624a861..d93f159 100644
> --- a/qapi/common.json
> +++ b/qapi/common.json
> @@ -1,6 +1,8 @@
>  # -*- Mode: Python -*-
> -#
> -# QAPI common definitions
> +
> +##
> +# = QAPI common definitions
> +##
>  
>  ##
>  # @QapiErrorClass:
> diff --git a/qapi/crypto.json b/qapi/crypto.json
> index 15d296e..1e517b0 100644
> --- a/qapi/crypto.json
> +++ b/qapi/crypto.json
> @@ -1,6 +1,9 @@
>  # -*- Mode: Python -*-
>  #
> -# QAPI crypto definitions
> +
> +##
> +# = QAPI crypto definitions
> +##
>  
>  ##
>  # @QCryptoTLSCredsEndpoint:
> diff --git a/qapi/event.json b/qapi/event.json
> index 37bf34e..59942b0 100644
> --- a/qapi/event.json
> +++ b/qapi/event.json
> @@ -1,3 +1,9 @@
> +# -*- Mode: Python -*-
> +
> +##
> +# = Events
> +##
> +

This suggests *all* events are in this section, which isn't the case.
"Other events"?  "Core events"?  Dunno...

>  ##
>  # @SHUTDOWN:
>  #
> diff --git a/qapi/rocker.json b/qapi/rocker.json
> index ace2776..dd72e02 100644
> --- a/qapi/rocker.json
> +++ b/qapi/rocker.json
> @@ -1,4 +1,8 @@
>  ##
> +# = Rocker API

What about "Rocker switch device"?

> +##
> +
> +##
>  # @RockerSwitch:
>  #
>  # Rocker switch information.
> diff --git a/qapi/trace.json b/qapi/trace.json
> index 4fd39b7..3ad7df7 100644
> --- a/qapi/trace.json
> +++ b/qapi/trace.json
> @@ -5,6 +5,9 @@
>  # This work is licensed under the terms of the GNU GPL, version 2 or later.
>  # See the COPYING file in the top-level directory.
>  
> +##
> +# = Tracing commands
> +##
>  
>  ##
>  # @TraceEventState: