[PATCH 0/4] qapi: Minor doc and markup fixes

[PATCH 0/4] qapi: Minor doc and markup fixes

[Markus Armbruster]

PATCH 3+4 conflict with "[PATCH 0/8] qapi: last minute
improvements/changes to -compat insecure-types" Daniel just posted.
I'm posting anyway to get some eyes on this.  I can take care of the
conflicts.

Markus Armbruster (4):
  qapi/acpi-hest: Fix markup of heading
  qapi: Fix inaccurate comment on pragma member-name-exceptions
  qapi/compat: Fix inaccurate CompatPolicy introduction
  qapi/compat: Fix "only syntactic aspects of QMP" note

 qapi/acpi-hest.json |  3 ++-
 qapi/compat.json    | 17 +++++++++--------
 qapi/pragma.json    |  2 +-
 3 files changed, 12 insertions(+), 10 deletions(-)

-- 
2.55.0

[PATCH 1/4] qapi/acpi-hest: Fix markup of heading

[Markus Armbruster]

The docs generated for qapi/acpi-hest.json shows text "== GHESv2 CPER
Error Injection" instead of a heading.  This is because the patch that
added the heading crossed with the commit that changed heading
markup (commit 6c10778826a "docs/sphinx: remove special parsing for
freeform sections").  Fix the markup.

Fixes: ddd8f3baa27d ("qapi/acpi-hest: add an interface to do generic CPER error injection")
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/acpi-hest.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/qapi/acpi-hest.json b/qapi/acpi-hest.json
index 8db804df19..505f68e053 100644
--- a/qapi/acpi-hest.json
+++ b/qapi/acpi-hest.json
@@ -3,7 +3,8 @@
 # SPDX-License-Identifier: GPL-2.0-or-later
 
 ##
-# == GHESv2 CPER Error Injection
+# GHESv2 CPER Error Injection
+# ===========================
 #
 # Defined since ACPI Specification 6.1, section 18.3.2.8 Generic
 # Hardware Error Source version 2.  See:
-- 
2.55.0

Re: [PATCH 1/4] qapi/acpi-hest: Fix markup of heading

[Daniel P. Berrangé]

On Wed, Oct 28, 2026 at 03:40:20PM +0100, Markus Armbruster wrote:
> The docs generated for qapi/acpi-hest.json shows text "== GHESv2 CPER
> Error Injection" instead of a heading.  This is because the patch that
> added the heading crossed with the commit that changed heading
> markup (commit 6c10778826a "docs/sphinx: remove special parsing for
> freeform sections").  Fix the markup.
> 
> Fixes: ddd8f3baa27d ("qapi/acpi-hest: add an interface to do generic CPER error injection")
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  qapi/acpi-hest.json | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


With regards,
Daniel
-- 
|: https://berrange.com       ~~        https://hachyderm.io/@berrange :|
|: https://libvirt.org          ~~          https://entangle-photo.org :|
|: https://pixelfed.art/berrange   ~~    https://fstop138.berrange.com :|

[PATCH 2/4] qapi: Fix inaccurate comment on pragma member-name-exceptions

[Markus Armbruster]

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/pragma.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/qapi/pragma.json b/qapi/pragma.json
index 342cedc42e..73807abc6a 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -80,7 +80,7 @@
         'XDbgBlockGraph',
         'YankInstanceType',
         'blockdev-reopen' ],
-    # Externally visible types whose member names may use uppercase
+    # Externally visible types whose member names may use uppercase or '_'
     'member-name-exceptions': [     # visible in:
         'ACPISlotType',             # query-acpi-ospm-status
         'AcpiTableOptions',         # -acpitable
-- 
2.55.0

Re: [PATCH 2/4] qapi: Fix inaccurate comment on pragma member-name-exceptions

[Daniel P. Berrangé]

On Wed, Oct 28, 2026 at 03:40:21PM +0100, Markus Armbruster wrote:
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  qapi/pragma.json | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


With regards,
Daniel
-- 
|: https://berrange.com       ~~        https://hachyderm.io/@berrange :|
|: https://libvirt.org          ~~          https://entangle-photo.org :|
|: https://pixelfed.art/berrange   ~~    https://fstop138.berrange.com :|

[PATCH 3/4] qapi/compat: Fix inaccurate CompatPolicy introduction

[Markus Armbruster]

"Policy for handling deprecated management interfaces" was initially
accurate, but we neglected to update it when we added policy for
unstable and insecure interfaces.  Change it to "problematic
management interfaces".

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/compat.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/qapi/compat.json b/qapi/compat.json
index 0f90ea1f52..f6bc93904f 100644
--- a/qapi/compat.json
+++ b/qapi/compat.json
@@ -53,7 +53,7 @@
 
 ##
 # @CompatPolicy:
-#     Policy for handling deprecated management interfaces.
+#     Policy for handling problematic management interfaces.
 #
 #     This is intended for testing users of the management interfaces.
 #
-- 
2.55.0

Re: [PATCH 3/4] qapi/compat: Fix inaccurate CompatPolicy introduction

[Daniel P. Berrangé]

On Wed, Oct 28, 2026 at 03:40:22PM +0100, Markus Armbruster wrote:
> "Policy for handling deprecated management interfaces" was initially
> accurate, but we neglected to update it when we added policy for
> unstable and insecure interfaces.  Change it to "problematic
> management interfaces".
> 
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  qapi/compat.json | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


With regards,
Daniel
-- 
|: https://berrange.com       ~~        https://hachyderm.io/@berrange :|
|: https://libvirt.org          ~~          https://entangle-photo.org :|
|: https://pixelfed.art/berrange   ~~    https://fstop138.berrange.com :|

[PATCH 4/4] qapi/compat: Fix "only syntactic aspects of QMP" note

[Markus Armbruster]

"Covers only syntactic aspects of QMP" was initially accurate, but we
we neglected to update it when we added @insecure-types.  Do that now.

While there, move the limitation notes below the enum value
descriptions to avoid forward references, and mark up an existing
reference properly.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/compat.json | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/qapi/compat.json b/qapi/compat.json
index f6bc93904f..d1fb74abf7 100644
--- a/qapi/compat.json
+++ b/qapi/compat.json
@@ -57,13 +57,6 @@
 #
 #     This is intended for testing users of the management interfaces.
 #
-# Limitation: covers only syntactic aspects of QMP, i.e. stuff tagged
-# with feature 'deprecated' or 'unstable'.  We may want to extend it
-# to cover semantic aspects and CLI.
-#
-# Limitation: deprecated-output policy @hide is not implemented for
-# enumeration values.  They behave the same as with policy @accept.
-#
 # @deprecated-input: how to handle deprecated input (default 'accept')
 #
 # @deprecated-output: how to handle deprecated output (default
@@ -78,6 +71,14 @@
 # @insecure-types: how to handle types that are not declared secure
 #     (default 'accept') (since 11.2)
 #
+# Limitation: @deprecated-input, @deprecated-output, @unstable-input,
+# and @unstable-output cover only syntactic aspects of QMP, i.e. stuff
+# tagged with feature 'deprecated' or 'unstable'.  We may want to
+# extend it to cover semantic aspects and CLI.
+#
+# Limitation: @deprecated-output policy @hide is not implemented for
+# enumeration values.  They behave the same as with policy @accept.
+#
 # Since: 6.0
 ##
 { 'struct': 'CompatPolicy',
-- 
2.55.0

Re: [PATCH 4/4] qapi/compat: Fix "only syntactic aspects of QMP" note

[Daniel P. Berrangé]

On Wed, Oct 28, 2026 at 03:40:23PM +0100, Markus Armbruster wrote:
> "Covers only syntactic aspects of QMP" was initially accurate, but we
> we neglected to update it when we added @insecure-types.  Do that now.
> 
> While there, move the limitation notes below the enum value
> descriptions to avoid forward references, and mark up an existing
> reference properly.
> 
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  qapi/compat.json | 15 ++++++++-------
>  1 file changed, 8 insertions(+), 7 deletions(-)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


With regards,
Daniel
-- 
|: https://berrange.com       ~~        https://hachyderm.io/@berrange :|
|: https://libvirt.org          ~~          https://entangle-photo.org :|
|: https://pixelfed.art/berrange   ~~    https://fstop138.berrange.com :|

[PATCH 0/4] qapi: Minor doc and markup fixes

[Markus Armbruster]

PATCH 3+4 conflict with "[PATCH 0/8] qapi: last minute
improvements/changes to -compat insecure-types" Daniel just posted.
I'm posting anyway to get some eyes on this.  I can take care of the
conflicts.

Markus Armbruster (4):
  qapi/acpi-hest: Fix markup of heading
  qapi: Fix inaccurate comment on pragma member-name-exceptions
  qapi/compat: Fix inaccurate CompatPolicy introduction
  qapi/compat: Fix "only syntactic aspects of QMP" note

 qapi/acpi-hest.json |  3 ++-
 qapi/compat.json    | 17 +++++++++--------
 qapi/pragma.json    |  2 +-
 3 files changed, 12 insertions(+), 10 deletions(-)

-- 
2.55.0

[PATCH 1/4] qapi/acpi-hest: Fix markup of heading

[Markus Armbruster]

The docs generated for qapi/acpi-hest.json shows text "== GHESv2 CPER
Error Injection" instead of a heading.  This is because the patch that
added the heading crossed with the commit that changed heading
markup (commit 6c10778826a "docs/sphinx: remove special parsing for
freeform sections").  Fix the markup.

Fixes: ddd8f3baa27d ("qapi/acpi-hest: add an interface to do generic CPER error injection")
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/acpi-hest.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/qapi/acpi-hest.json b/qapi/acpi-hest.json
index 8db804df19..505f68e053 100644
--- a/qapi/acpi-hest.json
+++ b/qapi/acpi-hest.json
@@ -3,7 +3,8 @@
 # SPDX-License-Identifier: GPL-2.0-or-later
 
 ##
-# == GHESv2 CPER Error Injection
+# GHESv2 CPER Error Injection
+# ===========================
 #
 # Defined since ACPI Specification 6.1, section 18.3.2.8 Generic
 # Hardware Error Source version 2.  See:
-- 
2.55.0

[PATCH 2/4] qapi: Fix inaccurate comment on pragma member-name-exceptions

[Markus Armbruster]

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/pragma.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/qapi/pragma.json b/qapi/pragma.json
index 342cedc42e..73807abc6a 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -80,7 +80,7 @@
         'XDbgBlockGraph',
         'YankInstanceType',
         'blockdev-reopen' ],
-    # Externally visible types whose member names may use uppercase
+    # Externally visible types whose member names may use uppercase or '_'
     'member-name-exceptions': [     # visible in:
         'ACPISlotType',             # query-acpi-ospm-status
         'AcpiTableOptions',         # -acpitable
-- 
2.55.0

[PATCH 3/4] qapi/compat: Fix inaccurate CompatPolicy introduction

[Markus Armbruster]

"Policy for handling deprecated management interfaces" was initially
accurate, but we neglected to update it when we added policy for
unstable and insecure interfaces.  Change it to "problematic
management interfaces".

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/compat.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/qapi/compat.json b/qapi/compat.json
index 0f90ea1f52..f6bc93904f 100644
--- a/qapi/compat.json
+++ b/qapi/compat.json
@@ -53,7 +53,7 @@
 
 ##
 # @CompatPolicy:
-#     Policy for handling deprecated management interfaces.
+#     Policy for handling problematic management interfaces.
 #
 #     This is intended for testing users of the management interfaces.
 #
-- 
2.55.0

[PATCH 4/4] qapi/compat: Fix "only syntactic aspects of QMP" note

[Markus Armbruster]

"Covers only syntactic aspects of QMP" was initially accurate, but we
we neglected to update it when we added @insecure-types.  Do that now.

While there, move the limitation notes below the enum value
descriptions to avoid forward references, and mark up an existing
reference properly.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/compat.json | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/qapi/compat.json b/qapi/compat.json
index f6bc93904f..d1fb74abf7 100644
--- a/qapi/compat.json
+++ b/qapi/compat.json
@@ -57,13 +57,6 @@
 #
 #     This is intended for testing users of the management interfaces.
 #
-# Limitation: covers only syntactic aspects of QMP, i.e. stuff tagged
-# with feature 'deprecated' or 'unstable'.  We may want to extend it
-# to cover semantic aspects and CLI.
-#
-# Limitation: deprecated-output policy @hide is not implemented for
-# enumeration values.  They behave the same as with policy @accept.
-#
 # @deprecated-input: how to handle deprecated input (default 'accept')
 #
 # @deprecated-output: how to handle deprecated output (default
@@ -78,6 +71,14 @@
 # @insecure-types: how to handle types that are not declared secure
 #     (default 'accept') (since 11.2)
 #
+# Limitation: @deprecated-input, @deprecated-output, @unstable-input,
+# and @unstable-output cover only syntactic aspects of QMP, i.e. stuff
+# tagged with feature 'deprecated' or 'unstable'.  We may want to
+# extend it to cover semantic aspects and CLI.
+#
+# Limitation: @deprecated-output policy @hide is not implemented for
+# enumeration values.  They behave the same as with policy @accept.
+#
 # Since: 6.0
 ##
 { 'struct': 'CompatPolicy',
-- 
2.55.0