[Qemu-devel] [PATCH 0/3] qapi-schema: Generated doc structure fixes

[Qemu-devel] [PATCH 0/3] qapi-schema: Generated doc structure fixes

[Markus Armbruster]

Markus Armbruster (3):
  qapi-schema: Document how generated documentation is ordered
  qapi-schema: Introspection doc is in the wrong section, fix
  qapi-schema: Rocker doc section contains unrelated stuff, fix

 qapi-schema.json     | 21 +++++++--------------
 qapi/introspect.json |  6 ++++--
 2 files changed, 11 insertions(+), 16 deletions(-)

-- 
2.7.5

[Qemu-devel] [PATCH 1/3] qapi-schema: Document how generated documentation is ordered

[Markus Armbruster]

Documentation generated with qapi2texi.py is in textual order, with
included sub-schemas inserted at the first include directive
(subsequent include directives have no effect).  To get a sane and
stable order, it's best to include each sub-schema just once, or
include it first in qapi-schema.json.  Document that.

While there, drop a few redundant comments.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi-schema.json | 17 ++++++-----------
 1 file changed, 6 insertions(+), 11 deletions(-)

diff --git a/qapi-schema.json b/qapi-schema.json
index 802ea53..76b5888 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -72,22 +72,17 @@
         'q_obj_CpuInfo-base'    # CPU, visible through query-cpu
     ] } }
 
-# QAPI common definitions
+# Documentation generated with qapi2texi.py is in textual order, with
+# included sub-schemas inserted at the first include directive
+# (subsequent include directives have no effect).  To get a sane and
+# stable order, it's best to include each sub-schema just once, or
+# include it first in qapi-schema.json.
+
 { 'include': 'qapi/common.json' }
-
-# QAPI crypto definitions
 { 'include': 'qapi/crypto.json' }
-
-# QAPI block definitions
 { 'include': 'qapi/block.json' }
-
-# QAPI event definitions
 { 'include': 'qapi/event.json' }
-
-# Tracing commands
 { 'include': 'qapi/trace.json' }
-
-# QAPI introspection
 { 'include': 'qapi/introspect.json' }
 
 ##
-- 
2.7.5

[Qemu-devel] [PATCH 2/3] qapi-schema: Introspection doc is in the wrong section, fix

[Markus Armbruster]

Bug: introspection documentation is in section "Tracing commands".

Cause: sub-schema qapi/introspect.json lacks a section header, and
therefore goes into whatever section precedes its include.

Fix: add a section header.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/introspect.json | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/qapi/introspect.json b/qapi/introspect.json
index cf77ff0..5b3e6e9 100644
--- a/qapi/introspect.json
+++ b/qapi/introspect.json
@@ -1,7 +1,5 @@
 # -*- Mode: Python -*-
 #
-# QAPI/QMP introspection
-#
 # Copyright (C) 2015 Red Hat, Inc.
 #
 # Authors:
@@ -11,6 +9,10 @@
 # See the COPYING file in the top-level directory.
 
 ##
+# = QMP introspection
+##
+
+##
 # @query-qmp-schema:
 #
 # Command query-qmp-schema exposes the QMP wire ABI as an array of
-- 
2.7.5

[Qemu-devel] [PATCH 3/3] qapi-schema: Rocker doc section contains unrelated stuff, fix

[Markus Armbruster]

Bug: section "Rocker switch device" starts with the rocker stuff, but
then has unrelated stuff, like ReplayMode, xen-load-devices-state, ...

Cause: rocker.json is included in the middle of section "QMP commands".

Fix: include it in a sane place, namely next to the other sub-schemas.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi-schema.json | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/qapi-schema.json b/qapi-schema.json
index 76b5888..81cef23 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -82,6 +82,7 @@
 { 'include': 'qapi/crypto.json' }
 { 'include': 'qapi/block.json' }
 { 'include': 'qapi/event.json' }
+{ 'include': 'qapi/rocker.json' }
 { 'include': 'qapi/trace.json' }
 { 'include': 'qapi/introspect.json' }
 
@@ -6273,9 +6274,6 @@
 ##
 { 'command': 'rtc-reset-reinjection' }
 
-# Rocker ethernet network switch
-{ 'include': 'qapi/rocker.json' }
-
 ##
 # @ReplayMode:
 #
-- 
2.7.5

Re: [Qemu-devel] [PATCH 2/3] qapi-schema: Introspection doc is in the wrong section, fix

[Marc-André Lureau]

On Thu, Aug 24, 2017 at 2:02 PM, Markus Armbruster <armbru@redhat.com> wrote:
> Bug: introspection documentation is in section "Tracing commands".
>
> Cause: sub-schema qapi/introspect.json lacks a section header, and
> therefore goes into whatever section precedes its include.
>
> Fix: add a section header.
>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

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


> ---
>  qapi/introspect.json | 6 ++++--
>  1 file changed, 4 insertions(+), 2 deletions(-)
>
> diff --git a/qapi/introspect.json b/qapi/introspect.json
> index cf77ff0..5b3e6e9 100644
> --- a/qapi/introspect.json
> +++ b/qapi/introspect.json
> @@ -1,7 +1,5 @@
>  # -*- Mode: Python -*-
>  #
> -# QAPI/QMP introspection
> -#
>  # Copyright (C) 2015 Red Hat, Inc.
>  #
>  # Authors:
> @@ -11,6 +9,10 @@
>  # See the COPYING file in the top-level directory.
>
>  ##
> +# = QMP introspection
> +##
> +
> +##
>  # @query-qmp-schema:
>  #
>  # Command query-qmp-schema exposes the QMP wire ABI as an array of
> --
> 2.7.5
>
>



-- 
Marc-André Lureau

Re: [Qemu-devel] [PATCH 3/3] qapi-schema: Rocker doc section contains unrelated stuff, fix

[Marc-André Lureau]

On Thu, Aug 24, 2017 at 2:02 PM, Markus Armbruster <armbru@redhat.com> wrote:
> Bug: section "Rocker switch device" starts with the rocker stuff, but
> then has unrelated stuff, like ReplayMode, xen-load-devices-state, ...
>
> Cause: rocker.json is included in the middle of section "QMP commands".
>
> Fix: include it in a sane place, namely next to the other sub-schemas.
>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

> ---
>  qapi-schema.json | 4 +---
>  1 file changed, 1 insertion(+), 3 deletions(-)
>
> diff --git a/qapi-schema.json b/qapi-schema.json
> index 76b5888..81cef23 100644
> --- a/qapi-schema.json
> +++ b/qapi-schema.json
> @@ -82,6 +82,7 @@
>  { 'include': 'qapi/crypto.json' }
>  { 'include': 'qapi/block.json' }
>  { 'include': 'qapi/event.json' }
> +{ 'include': 'qapi/rocker.json' }
>  { 'include': 'qapi/trace.json' }
>  { 'include': 'qapi/introspect.json' }
>
> @@ -6273,9 +6274,6 @@
>  ##
>  { 'command': 'rtc-reset-reinjection' }
>
> -# Rocker ethernet network switch
> -{ 'include': 'qapi/rocker.json' }
> -
>  ##
>  # @ReplayMode:
>  #
> --
> 2.7.5
>
>



-- 
Marc-André Lureau

Re: [Qemu-devel] [PATCH 3/3] qapi-schema: Rocker doc section contains unrelated stuff, fix

[Marc-André Lureau]

On Thu, Aug 24, 2017 at 2:02 PM, Markus Armbruster <armbru@redhat.com> wrote:
> Bug: section "Rocker switch device" starts with the rocker stuff, but
> then has unrelated stuff, like ReplayMode, xen-load-devices-state, ...
>
> Cause: rocker.json is included in the middle of section "QMP commands".
>
> Fix: include it in a sane place, namely next to the other sub-schemas.
>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>


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


> ---
>  qapi-schema.json | 4 +---
>  1 file changed, 1 insertion(+), 3 deletions(-)
>
> diff --git a/qapi-schema.json b/qapi-schema.json
> index 76b5888..81cef23 100644
> --- a/qapi-schema.json
> +++ b/qapi-schema.json
> @@ -82,6 +82,7 @@
>  { 'include': 'qapi/crypto.json' }
>  { 'include': 'qapi/block.json' }
>  { 'include': 'qapi/event.json' }
> +{ 'include': 'qapi/rocker.json' }
>  { 'include': 'qapi/trace.json' }
>  { 'include': 'qapi/introspect.json' }
>
> @@ -6273,9 +6274,6 @@
>  ##
>  { 'command': 'rtc-reset-reinjection' }
>
> -# Rocker ethernet network switch
> -{ 'include': 'qapi/rocker.json' }
> -
>  ##
>  # @ReplayMode:
>  #
> --
> 2.7.5
>
>



-- 
Marc-André Lureau

Re: [Qemu-devel] [PATCH 1/3] qapi-schema: Document how generated documentation is ordered

[Marc-André Lureau]

On Thu, Aug 24, 2017 at 2:02 PM, Markus Armbruster <armbru@redhat.com> wrote:
> Documentation generated with qapi2texi.py is in textual order, with
> included sub-schemas inserted at the first include directive
> (subsequent include directives have no effect).  To get a sane and
> stable order, it's best to include each sub-schema just once, or
> include it first in qapi-schema.json.  Document that.
>
> While there, drop a few redundant comments.
>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

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


> ---
>  qapi-schema.json | 17 ++++++-----------
>  1 file changed, 6 insertions(+), 11 deletions(-)
>
> diff --git a/qapi-schema.json b/qapi-schema.json
> index 802ea53..76b5888 100644
> --- a/qapi-schema.json
> +++ b/qapi-schema.json
> @@ -72,22 +72,17 @@
>          'q_obj_CpuInfo-base'    # CPU, visible through query-cpu
>      ] } }
>
> -# QAPI common definitions
> +# Documentation generated with qapi2texi.py is in textual order, with
> +# included sub-schemas inserted at the first include directive
> +# (subsequent include directives have no effect).  To get a sane and
> +# stable order, it's best to include each sub-schema just once, or
> +# include it first in qapi-schema.json.
> +
>  { 'include': 'qapi/common.json' }
> -
> -# QAPI crypto definitions
>  { 'include': 'qapi/crypto.json' }
> -
> -# QAPI block definitions
>  { 'include': 'qapi/block.json' }
> -
> -# QAPI event definitions
>  { 'include': 'qapi/event.json' }
> -
> -# Tracing commands
>  { 'include': 'qapi/trace.json' }
> -
> -# QAPI introspection
>  { 'include': 'qapi/introspect.json' }
>
>  ##
> --
> 2.7.5
>
>



-- 
Marc-André Lureau