[PATCH 00/11] qapi: Documentation improvements

[PATCH 00/11] qapi: Documentation improvements

[Markus Armbruster]

Markus Armbruster (11):
  docs/devel/qapi-code-gen: Tidy up whitespace
  qapi/rocker: Tidy up query-rocker-of-dpa-flows example
  docs/interop: Delete "QEMU Guest Agent Protocol Reference" TOC
  docs/interop: Sanitize QMP reference manuals TOC
  docs/devel/qapi-code-gen: Improve the part on qmp-example directive
  docs/sphinx/qmp_lexer: Generalize elision syntax
  docs/sphinx/qmp_lexer: Highlight elisions like comments, not prompts
  qapi/qapi-schema: Update introduction for example notation
  qapi/qapi-schema: Address the introduction's bit rot
  storage-daemon/qapi/qapi-schema: Add a proper introduction
  qga/qapi-schema: Add a proper introduction

 docs/devel/qapi-code-gen.rst                 | 53 ++++++++++++--------
 docs/interop/qemu-ga-ref.rst                 |  3 --
 docs/interop/qemu-qmp-ref.rst                |  2 +-
 docs/interop/qemu-storage-daemon-qmp-ref.rst |  2 +-
 docs/sphinx/qmp_lexer.py                     |  2 +-
 qapi/qapi-schema.json                        | 31 ++++--------
 qapi/rocker.json                             |  2 +-
 qga/qapi-schema.json                         | 20 ++++++--
 storage-daemon/qapi/qapi-schema.json         | 22 ++++++--
 tests/qapi-schema/doc-good.json              |  2 +-
 tests/qapi-schema/doc-good.out               |  2 +-
 tests/qapi-schema/doc-good.txt               |  2 +-
 12 files changed, 83 insertions(+), 60 deletions(-)

-- 
2.48.1

[PATCH 01/11] docs/devel/qapi-code-gen: Tidy up whitespace

[Markus Armbruster]

Consistently use two spaces to separate sentences.

Put "::" on a line of its own when it's preceded by whitespace.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 docs/devel/qapi-code-gen.rst | 26 ++++++++++++++------------
 1 file changed, 14 insertions(+), 12 deletions(-)

diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index f9cfe8721f..ad517349fc 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -763,8 +763,8 @@ Names beginning with ``x-`` used to signify "experimental".  This
 convention has been replaced by special feature "unstable".
 
 Pragmas ``command-name-exceptions`` and ``member-name-exceptions`` let
-you violate naming rules.  Use for new code is strongly discouraged. See
-`Pragma directives`_ for details.
+you violate naming rules.  Use for new code is strongly discouraged.
+See `Pragma directives`_ for details.
 
 
 Downstream extensions
@@ -1013,7 +1013,7 @@ like this::
 document the success and the error response, respectively.
 
 "Errors" sections should be formatted as an rST list, each entry
-detailing a relevant error condition. For example::
+detailing a relevant error condition.  For example::
 
  # Errors:
  #     - If @device does not exist, DeviceNotFound
@@ -1026,13 +1026,13 @@ definition.
 QMP).  In other sections, the text is formatted, and rST markup can be
 used.
 
-QMP Examples can be added by using the ``.. qmp-example::``
-directive. In its simplest form, this can be used to contain a single
-QMP code block which accepts standard JSON syntax with additional server
+QMP Examples can be added by using the ``.. qmp-example::`` directive.
+In its simplest form, this can be used to contain a single QMP code
+block which accepts standard JSON syntax with additional server
 directionality indicators (``->`` and ``<-``), and elisions (``...``).
 
 Optionally, a plaintext title may be provided by using the ``:title:``
-directive option. If the title is omitted, the example title will
+directive option.  If the title is omitted, the example title will
 default to "Example:".
 
 A simple QMP example::
@@ -1043,10 +1043,10 @@ A simple QMP example::
   #    -> { "execute": "query-block" }
   #    <- { ... }
 
-More complex or multi-step examples where exposition is needed before or
-between QMP code blocks can be created by using the ``:annotated:``
-directive option. When using this option, nested QMP code blocks must be
-entered explicitly with rST's ``::`` syntax.
+More complex or multi-step examples where exposition is needed before
+or between QMP code blocks can be created by using the ``:annotated:``
+directive option.  When using this option, nested QMP code blocks must
+be entered explicitly with rST's ``::`` syntax.
 
 Highlighting in non-QMP languages can be accomplished by using the
 ``.. code-block:: lang`` directive, and non-highlighted text can be
@@ -1466,7 +1466,9 @@ As an example, we'll use the following schema, which describes a
 single complex user-defined type, along with command which takes a
 list of that type as a parameter, and returns a single element of that
 type.  The user is responsible for writing the implementation of
-qmp_my_command(); everything else is produced by the generator. ::
+qmp_my_command(); everything else is produced by the generator.
+
+::
 
     $ cat example-schema.json
     { 'struct': 'UserDefOne',
-- 
2.48.1

[PATCH 02/11] qapi/rocker: Tidy up query-rocker-of-dpa-flows example

[Markus Armbruster]

The command can return any number of RockerOfDpaFlow objects.  The
example shows it returning exactly two, with the second objecy's
members elided.  Tweak it so it elides elements after the first
instead.

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

diff --git a/qapi/rocker.json b/qapi/rocker.json
index 51aa5b4930..0c7ef1f77c 100644
--- a/qapi/rocker.json
+++ b/qapi/rocker.json
@@ -254,7 +254,7 @@
 #                       "action": {"goto-tbl": 10},
 #                       "mask": {"in-pport": 4294901760}
 #                      },
-#                      {...},
+#                      ...
 #        ]}
 ##
 { 'command': 'query-rocker-of-dpa-flows',
-- 
2.48.1

Re: [PATCH 02/11] qapi/rocker: Tidy up query-rocker-of-dpa-flows example

[Eric Blake]

On Fri, Apr 04, 2025 at 02:14:04PM +0200, Markus Armbruster wrote:
> The command can return any number of RockerOfDpaFlow objects.  The
> example shows it returning exactly two, with the second objecy's

object's

> members elided.  Tweak it so it elides elements after the first
> instead.
> 

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.
Virtualization:  qemu.org | libguestfs.org

Re: [PATCH 02/11] qapi/rocker: Tidy up query-rocker-of-dpa-flows example

[Markus Armbruster]

Eric Blake <eblake@redhat.com> writes:

> On Fri, Apr 04, 2025 at 02:14:04PM +0200, Markus Armbruster wrote:
>> The command can return any number of RockerOfDpaFlow objects.  The
>> example shows it returning exactly two, with the second objecy's
>
> object's

Fixing...  thanks!

>> members elided.  Tweak it so it elides elements after the first
>> instead.

[PATCH 03/11] docs/interop: Delete "QEMU Guest Agent Protocol Reference" TOC

[Markus Armbruster]

The "QEMU Guest Agent Protocol Reference" starts with the following
table of contents:

    Contents

    * QEMU Guest Agent Protocol Reference

      * QEMU guest agent protocol commands and structs

This is useless.  Delete the entire TOC.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 docs/interop/qemu-ga-ref.rst | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/docs/interop/qemu-ga-ref.rst b/docs/interop/qemu-ga-ref.rst
index 19b5c7a549..25f6e24b03 100644
--- a/docs/interop/qemu-ga-ref.rst
+++ b/docs/interop/qemu-ga-ref.rst
@@ -1,9 +1,6 @@
 QEMU Guest Agent Protocol Reference
 ===================================
 
-.. contents::
-   :depth: 3
-
 .. qapi-doc:: qga/qapi-schema.json
    :transmogrify:
    :namespace: QGA
-- 
2.48.1

[PATCH 04/11] docs/interop: Sanitize QMP reference manuals TOC

[Markus Armbruster]

The "QEMU QMP Reference Manual" and the "QEMU Storage Daemon QMP
Reference Manual" start with a table of contents that looks like this:

    Contents

    * Title of the manual
      * Title of first first-level section
        * Title of its first second-level section
        * Title of its second second-level section
        ...
      * Title of second first-level section
      ...

The first level is useless.  Drop it.

While there, delete the option that limits the TOC to depth 3.  Its
actual depth was 3 before the patch, and is now 2.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 docs/interop/qemu-qmp-ref.rst                | 2 +-
 docs/interop/qemu-storage-daemon-qmp-ref.rst | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/interop/qemu-qmp-ref.rst b/docs/interop/qemu-qmp-ref.rst
index ef8792b53f..3bc1ca12b1 100644
--- a/docs/interop/qemu-qmp-ref.rst
+++ b/docs/interop/qemu-qmp-ref.rst
@@ -4,7 +4,7 @@ QEMU QMP Reference Manual
 =========================
 
 .. contents::
-   :depth: 3
+   :local:
 
 .. qapi-doc:: qapi/qapi-schema.json
    :transmogrify:
diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qemu-storage-daemon-qmp-ref.rst
index d0228d63b8..dc7bde262a 100644
--- a/docs/interop/qemu-storage-daemon-qmp-ref.rst
+++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst
@@ -2,7 +2,7 @@ QEMU Storage Daemon QMP Reference Manual
 ========================================
 
 .. contents::
-   :depth: 3
+   :local:
 
 .. qapi-doc:: storage-daemon/qapi/qapi-schema.json
    :transmogrify:
-- 
2.48.1

[PATCH 05/11] docs/devel/qapi-code-gen: Improve the part on qmp-example directive

[Markus Armbruster]

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 docs/devel/qapi-code-gen.rst | 23 ++++++++++++++---------
 1 file changed, 14 insertions(+), 9 deletions(-)

diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index ad517349fc..25a46fafb6 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -1038,20 +1038,15 @@ default to "Example:".
 A simple QMP example::
 
   # .. qmp-example::
-  #    :title: Using query-block
   #
-  #    -> { "execute": "query-block" }
-  #    <- { ... }
+  #     -> { "execute": "query-name" }
+  #     <- { "return": { "name": "Fred" } }
 
 More complex or multi-step examples where exposition is needed before
 or between QMP code blocks can be created by using the ``:annotated:``
 directive option.  When using this option, nested QMP code blocks must
 be entered explicitly with rST's ``::`` syntax.
 
-Highlighting in non-QMP languages can be accomplished by using the
-``.. code-block:: lang`` directive, and non-highlighted text can be
-achieved by omitting the language argument.
-
 For example::
 
   # .. qmp-example::
@@ -1061,11 +1056,21 @@ For example::
   #    This is a more complex example that can use
   #    ``arbitrary rST syntax`` in its exposition::
   #
-  #      -> { "execute": "query-block" }
-  #      <- { ... }
+  #     -> { "execute": "query-block" }
+  #     <- { "return": [
+  #             {
+  #               "device": "ide0-hd0",
+  #               ...
+  #             }
+  #             ...
+  #          ] }
   #
   #    Above, lengthy output has been omitted for brevity.
 
+Highlighting in non-QMP languages can be accomplished by using the
+``.. code-block:: lang`` directive, and non-highlighted text can be
+achieved by omitting the language argument.
+
 
 Examples of complete definition documentation::
 
-- 
2.48.1

[PATCH 06/11] docs/sphinx/qmp_lexer: Generalize elision syntax

[Markus Armbruster]

Accept "... lorem ipsum ..."  in addition to "...".

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 docs/devel/qapi-code-gen.rst    | 6 ++++--
 docs/sphinx/qmp_lexer.py        | 2 +-
 tests/qapi-schema/doc-good.json | 2 +-
 tests/qapi-schema/doc-good.out  | 2 +-
 tests/qapi-schema/doc-good.txt  | 2 +-
 5 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index 25a46fafb6..231cc0fecf 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -1029,7 +1029,9 @@ used.
 QMP Examples can be added by using the ``.. qmp-example::`` directive.
 In its simplest form, this can be used to contain a single QMP code
 block which accepts standard JSON syntax with additional server
-directionality indicators (``->`` and ``<-``), and elisions (``...``).
+directionality indicators (``->`` and ``<-``), and elisions.  An
+elision is commonly ``...``, but it can also be or a pair of ``...``
+with text in between.
 
 Optionally, a plaintext title may be provided by using the ``:title:``
 directive option.  If the title is omitted, the example title will
@@ -1062,7 +1064,7 @@ For example::
   #               "device": "ide0-hd0",
   #               ...
   #             }
-  #             ...
+  #             ... more ...
   #          ] }
   #
   #    Above, lengthy output has been omitted for brevity.
diff --git a/docs/sphinx/qmp_lexer.py b/docs/sphinx/qmp_lexer.py
index a59de8a079..1bd1b81b70 100644
--- a/docs/sphinx/qmp_lexer.py
+++ b/docs/sphinx/qmp_lexer.py
@@ -24,7 +24,7 @@ class QMPExampleMarkersLexer(RegexLexer):
         'root': [
             (r'-> ', token.Generic.Prompt),
             (r'<- ', token.Generic.Prompt),
-            (r' ?\.{3} ?', token.Generic.Prompt),
+            (r'\.{3}( .* \.{3})?', token.Generic.Prompt),
         ]
     }
 
diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
index 0a4f139f83..14b808f909 100644
--- a/tests/qapi-schema/doc-good.json
+++ b/tests/qapi-schema/doc-good.json
@@ -212,7 +212,7 @@
 #
 #    -> "this example"
 #
-#    <- "has no title"
+#    <- ... has no title ...
 ##
 { 'command': 'cmd-boxed', 'boxed': true,
   'data': 'Object',
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index 5773f1dd6d..dc8352eed4 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -217,7 +217,7 @@ another feature
 
    -> "this example"
 
-   <- "has no title"
+   <- ... has no title ...
 doc symbol=EVT_BOXED
     body=
 
diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt
index cb37db606a..17a1d56ef1 100644
--- a/tests/qapi-schema/doc-good.txt
+++ b/tests/qapi-schema/doc-good.txt
@@ -264,7 +264,7 @@ Example::
 
    -> "this example"
 
-   <- "has no title"
+   <- ... has no title ...
 
 
 "EVT_BOXED" (Event)
-- 
2.48.1

Re: [PATCH 06/11] docs/sphinx/qmp_lexer: Generalize elision syntax

[Eric Blake]

On Fri, Apr 04, 2025 at 02:14:08PM +0200, Markus Armbruster wrote:
> Accept "... lorem ipsum ..."  in addition to "...".
> 
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
> @@ -1062,7 +1064,7 @@ For example::
>    #               "device": "ide0-hd0",
>    #               ...
>    #             }
> -  #             ...
> +  #             ... more ...
>    #          ] }

Nice.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.
Virtualization:  qemu.org | libguestfs.org

Re: [PATCH 06/11] docs/sphinx/qmp_lexer: Generalize elision syntax

[John Snow]

[-- Attachment #1: Type: text/plain, Size: 3292 bytes --]

On Fri, Apr 4, 2025 at 8:14 AM Markus Armbruster <armbru@redhat.com> wrote:

> Accept "... lorem ipsum ..."  in addition to "...".
>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  docs/devel/qapi-code-gen.rst    | 6 ++++--
>  docs/sphinx/qmp_lexer.py        | 2 +-
>  tests/qapi-schema/doc-good.json | 2 +-
>  tests/qapi-schema/doc-good.out  | 2 +-
>  tests/qapi-schema/doc-good.txt  | 2 +-
>  5 files changed, 8 insertions(+), 6 deletions(-)
>
> diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
> index 25a46fafb6..231cc0fecf 100644
> --- a/docs/devel/qapi-code-gen.rst
> +++ b/docs/devel/qapi-code-gen.rst
> @@ -1029,7 +1029,9 @@ used.
>  QMP Examples can be added by using the ``.. qmp-example::`` directive.
>  In its simplest form, this can be used to contain a single QMP code
>  block which accepts standard JSON syntax with additional server
> -directionality indicators (``->`` and ``<-``), and elisions (``...``).
> +directionality indicators (``->`` and ``<-``), and elisions.  An
> +elision is commonly ``...``, but it can also be or a pair of ``...``
> +with text in between.
>
>  Optionally, a plaintext title may be provided by using the ``:title:``
>  directive option.  If the title is omitted, the example title will
> @@ -1062,7 +1064,7 @@ For example::
>    #               "device": "ide0-hd0",
>    #               ...
>    #             }
> -  #             ...
> +  #             ... more ...
>    #          ] }
>    #
>    #    Above, lengthy output has been omitted for brevity.
> diff --git a/docs/sphinx/qmp_lexer.py b/docs/sphinx/qmp_lexer.py
> index a59de8a079..1bd1b81b70 100644
> --- a/docs/sphinx/qmp_lexer.py
> +++ b/docs/sphinx/qmp_lexer.py
> @@ -24,7 +24,7 @@ class QMPExampleMarkersLexer(RegexLexer):
>          'root': [
>              (r'-> ', token.Generic.Prompt),
>              (r'<- ', token.Generic.Prompt),
> -            (r' ?\.{3} ?', token.Generic.Prompt),
> +            (r'\.{3}( .* \.{3})?', token.Generic.Prompt),
>          ]
>      }
>
> diff --git a/tests/qapi-schema/doc-good.json
> b/tests/qapi-schema/doc-good.json
> index 0a4f139f83..14b808f909 100644
> --- a/tests/qapi-schema/doc-good.json
> +++ b/tests/qapi-schema/doc-good.json
> @@ -212,7 +212,7 @@
>  #
>  #    -> "this example"
>  #
> -#    <- "has no title"
> +#    <- ... has no title ...
>  ##
>  { 'command': 'cmd-boxed', 'boxed': true,
>    'data': 'Object',
> diff --git a/tests/qapi-schema/doc-good.out
> b/tests/qapi-schema/doc-good.out
> index 5773f1dd6d..dc8352eed4 100644
> --- a/tests/qapi-schema/doc-good.out
> +++ b/tests/qapi-schema/doc-good.out
> @@ -217,7 +217,7 @@ another feature
>
>     -> "this example"
>
> -   <- "has no title"
> +   <- ... has no title ...
>  doc symbol=EVT_BOXED
>      body=
>
> diff --git a/tests/qapi-schema/doc-good.txt
> b/tests/qapi-schema/doc-good.txt
> index cb37db606a..17a1d56ef1 100644
> --- a/tests/qapi-schema/doc-good.txt
> +++ b/tests/qapi-schema/doc-good.txt
> @@ -264,7 +264,7 @@ Example::
>
>     -> "this example"
>
> -   <- "has no title"
> +   <- ... has no title ...
>
>
>  "EVT_BOXED" (Event)
> --
> 2.48.1
>
>
Cool, sure!

ACK (Who is responsible for this now? Me?)

[-- Attachment #2: Type: text/html, Size: 4291 bytes --]

Re: [PATCH 06/11] docs/sphinx/qmp_lexer: Generalize elision syntax

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> On Fri, Apr 4, 2025 at 8:14 AM Markus Armbruster <armbru@redhat.com> wrote:
>
>> Accept "... lorem ipsum ..."  in addition to "...".
>>
>> Signed-off-by: Markus Armbruster <armbru@redhat.com>

[...]

> Cool, sure!
>
> ACK (Who is responsible for this now? Me?)

Yup.

I posted the PR without waiting for your approval only because I really,
really want to get the introductions right for 10.0, and the
docs/sphinx/ is just a one-liner.  Hope you don't mind!

[PATCH 07/11] docs/sphinx/qmp_lexer: Highlight elisions like comments, not prompts

[Markus Armbruster]

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 docs/sphinx/qmp_lexer.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/sphinx/qmp_lexer.py b/docs/sphinx/qmp_lexer.py
index 1bd1b81b70..7b3b808d12 100644
--- a/docs/sphinx/qmp_lexer.py
+++ b/docs/sphinx/qmp_lexer.py
@@ -24,7 +24,7 @@ class QMPExampleMarkersLexer(RegexLexer):
         'root': [
             (r'-> ', token.Generic.Prompt),
             (r'<- ', token.Generic.Prompt),
-            (r'\.{3}( .* \.{3})?', token.Generic.Prompt),
+            (r'\.{3}( .* \.{3})?', token.Comment.Multiline),
         ]
     }
 
-- 
2.48.1

[PATCH 08/11] qapi/qapi-schema: Update introduction for example notation

[Markus Armbruster]

The introduction explains example notation.  The series merged in
merge commit e6485190f77e (in 9.1) improved how they look in generated
docs, but neglected to update the introduction accordingly.  Do that
now.

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

diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json
index c41c01eb2a..0d027d5017 100644
--- a/qapi/qapi-schema.json
+++ b/qapi/qapi-schema.json
@@ -26,10 +26,10 @@
 #
 # Example:
 #
-# ::
+# .. qmp-example::
 #
-#   -> data issued by the Client
-#   <- Server data response
+#   -> ... text sent by client (commands) ...
+#   <- ... text sent by server (command responses and events) ...
 #
 # Please refer to the
 # :doc:`QEMU Machine Protocol Specification </interop/qmp-spec>`
-- 
2.48.1

[PATCH 09/11] qapi/qapi-schema: Address the introduction's bit rot

[Markus Armbruster]

Cut the crap that stopped making sense years ago.  Adjust the
remainder.

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

diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json
index 0d027d5017..7bc600bb76 100644
--- a/qapi/qapi-schema.json
+++ b/qapi/qapi-schema.json
@@ -3,37 +3,24 @@
 ##
 # = Introduction
 #
-# This document describes all commands currently supported by QMP.
+# This manual describes the commands and events supported by the QEMU
+# Monitor Protocol (QMP).
 #
 # For locating a particular item, please see the `qapi-qmp-index`.
 #
-# Most of the time their usage is exactly the same as in the user
-# Monitor, this means that any other document which also describe
-# commands (the manpage, QEMU's manual, etc) can and should be
-# consulted.
-#
-# QMP has two types of commands: regular and query commands.  Regular
-# commands usually change the Virtual Machine's state someway, while
-# query commands just return information.  The sections below are
-# divided accordingly.
-#
-# It's important to observe that all communication examples are
-# formatted in a reader-friendly way, so that they're easier to
-# understand.  However, in real protocol usage, they're emitted as a
-# single line.
-#
-# Also, the following notation is used to denote data flow:
-#
-# Example:
+# The following notation is used in examples:
 #
 # .. qmp-example::
 #
 #   -> ... text sent by client (commands) ...
 #   <- ... text sent by server (command responses and events) ...
 #
+# Example text is formatted for readability.  However, in real
+# protocol usage, its commonly emitted as a single line.
+#
 # Please refer to the
 # :doc:`QEMU Machine Protocol Specification </interop/qmp-spec>`
-# for detailed information on the Server command and response formats.
+# for the general format of commands, responses, and events.
 ##
 
 { 'include': 'pragma.json' }
-- 
2.48.1

Re: [PATCH 09/11] qapi/qapi-schema: Address the introduction's bit rot

[John Snow]

[-- Attachment #1: Type: text/plain, Size: 2283 bytes --]

On Fri, Apr 4, 2025 at 8:14 AM Markus Armbruster <armbru@redhat.com> wrote:

> Cut the crap that stopped making sense years ago.  Adjust the
> remainder.
>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  qapi/qapi-schema.json | 27 +++++++--------------------
>  1 file changed, 7 insertions(+), 20 deletions(-)
>
> diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json
> index 0d027d5017..7bc600bb76 100644
> --- a/qapi/qapi-schema.json
> +++ b/qapi/qapi-schema.json
> @@ -3,37 +3,24 @@
>  ##
>  # = Introduction
>  #
> -# This document describes all commands currently supported by QMP.
> +# This manual describes the commands and events supported by the QEMU
> +# Monitor Protocol (QMP).
>  #
>  # For locating a particular item, please see the `qapi-qmp-index`.
>  #
> -# Most of the time their usage is exactly the same as in the user
> -# Monitor, this means that any other document which also describe
> -# commands (the manpage, QEMU's manual, etc) can and should be
> -# consulted.
> -#
> -# QMP has two types of commands: regular and query commands.  Regular
> -# commands usually change the Virtual Machine's state someway, while
> -# query commands just return information.  The sections below are
> -# divided accordingly.
> -#
> -# It's important to observe that all communication examples are
> -# formatted in a reader-friendly way, so that they're easier to
> -# understand.  However, in real protocol usage, they're emitted as a
> -# single line.
> -#
> -# Also, the following notation is used to denote data flow:
> -#
> -# Example:
> +# The following notation is used in examples:
>  #
>  # .. qmp-example::
>  #
>  #   -> ... text sent by client (commands) ...
>  #   <- ... text sent by server (command responses and events) ...
>  #
> +# Example text is formatted for readability.  However, in real
> +# protocol usage, its commonly emitted as a single line.
> +#
>  # Please refer to the
>  # :doc:`QEMU Machine Protocol Specification </interop/qmp-spec>`
> -# for detailed information on the Server command and response formats.
> +# for the general format of commands, responses, and events.
>  ##
>
>  { 'include': 'pragma.json' }
> --
> 2.48.1


Thanks for this one :)

[-- Attachment #2: Type: text/html, Size: 2884 bytes --]

[PATCH 10/11] storage-daemon/qapi/qapi-schema: Add a proper introduction

[Markus Armbruster]

Contents adapted from qapi/qapi-schema.json.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 storage-daemon/qapi/qapi-schema.json | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/storage-daemon/qapi/qapi-schema.json b/storage-daemon/qapi/qapi-schema.json
index 2a562ee32e..0427594c98 100644
--- a/storage-daemon/qapi/qapi-schema.json
+++ b/storage-daemon/qapi/qapi-schema.json
@@ -14,10 +14,26 @@
 # storage daemon.
 
 ##
-# = QEMU storage daemon protocol commands and structs
+# = Introduction
 #
-# For a concise listing of all commands, events, and types in the QEMU
-# storage daemon, please consult the `qapi-qsd-index`.
+# This manual describes the commands and events supported by the QEMU
+# storage daemon QMP.
+#
+# For locating a particular item, please see the `qapi-qsd-index`.
+#
+# The following notation is used in examples:
+#
+# .. qmp-example::
+#
+#   -> ... text sent by client (commands) ...
+#   <- ... text sent by server (command responses and events) ...
+#
+# Example text is formatted for readability.  However, in real
+# protocol usage, its commonly emitted as a single line.
+#
+# Please refer to the
+# :doc:`QEMU Machine Protocol Specification </interop/qmp-spec>`
+# for the general format of commands, responses, and events.
 ##
 
 
-- 
2.48.1

[PATCH 11/11] qga/qapi-schema: Add a proper introduction

[Markus Armbruster]

Contents adapted from qapi/qapi-schema.json.

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

diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
index 35ec0e7db3..5316bfacbf 100644
--- a/qga/qapi-schema.json
+++ b/qga/qapi-schema.json
@@ -2,10 +2,24 @@
 # vim: filetype=python
 
 ##
-# = QEMU guest agent protocol commands and structs
+# This manual describes the commands supported by the QEMU Guest
+# Agent Protocol.
 #
-# For a concise listing of all commands, events, and types in the QEMU
-# guest agent, please consult the `qapi-qga-index`.
+# For locating  a particular item, please see the `qapi-qga-index`.
+#
+# The following notation is used in examples:
+#
+# .. qmp-example::
+#
+#   -> ... text sent by client (commands) ...
+#   <- ... text sent by server (command responses and events) ...
+#
+# Example text is formatted for readability.  However, in real
+# protocol usage, its commonly emitted as a single line.
+#
+# Please refer to the
+# :doc:`QEMU Machine Protocol Specification </interop/qmp-spec>`
+# for the general format of commands, responses, and events.
 ##
 
 { 'pragma': { 'doc-required': true } }
-- 
2.48.1

Re: [PATCH 00/11] qapi: Documentation improvements

[Eric Blake]

On Fri, Apr 04, 2025 at 02:14:02PM +0200, Markus Armbruster wrote:
> Markus Armbruster (11):
>   docs/devel/qapi-code-gen: Tidy up whitespace
>   qapi/rocker: Tidy up query-rocker-of-dpa-flows example
>   docs/interop: Delete "QEMU Guest Agent Protocol Reference" TOC
>   docs/interop: Sanitize QMP reference manuals TOC
>   docs/devel/qapi-code-gen: Improve the part on qmp-example directive
>   docs/sphinx/qmp_lexer: Generalize elision syntax
>   docs/sphinx/qmp_lexer: Highlight elisions like comments, not prompts
>   qapi/qapi-schema: Update introduction for example notation
>   qapi/qapi-schema: Address the introduction's bit rot
>   storage-daemon/qapi/qapi-schema: Add a proper introduction
>   qga/qapi-schema: Add a proper introduction

I noticed at least one typo and replied in-place, but overall the
series is good once you touch that up.  For the series:

Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.
Virtualization:  qemu.org | libguestfs.org

Re: [PATCH 00/11] qapi: Documentation improvements

[Markus Armbruster]

Queued for 10.0.