[PATCH 0/3] docs/devel/qapi-code-gen: Update x-ref syntax, minor fixes

[PATCH 0/3] docs/devel/qapi-code-gen: Update x-ref syntax, minor fixes

[Markus Armbruster]

Markus Armbruster (3):
  docs/devel/qapi-code-gen: Add two cross-references we missed
  docs/devel/qapi-code-gen: Fix typos in QAPI schema language grammar
  docs/devel/qapi-code-gen: Update cross-reference syntax

 docs/devel/qapi-code-gen.rst | 19 ++++++++++++-------
 docs/devel/qapi-domain.rst   |  1 +
 2 files changed, 13 insertions(+), 7 deletions(-)

-- 
2.49.0

[PATCH 1/3] docs/devel/qapi-code-gen: Add two cross-references we missed

[Markus Armbruster]

Missed in commit 9c66762a601 (docs/qapi-code-gen: add
cross-references).

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

diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index dfdbeac5a5..138921b386 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -646,9 +646,9 @@ Member 'event' names the event.  This is the event name used in the
 Client JSON Protocol.
 
 Member 'data' defines the event-specific data.  It defaults to an
-empty MEMBERS object.
+empty MEMBERS_ object.
 
-If 'data' is a MEMBERS object, then MEMBERS defines event-specific
+If 'data' is a MEMBERS_ object, then MEMBERS defines event-specific
 data just like a struct type's 'data' defines struct type members.
 
 If 'data' is a STRING, then STRING names a complex type whose members
-- 
2.49.0

[PATCH 2/3] docs/devel/qapi-code-gen: Fix typos in QAPI schema language grammar

[Markus Armbruster]

Fixes: 3248c1aaf2db (docs: update the documentation upfront about schema configuration)
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 docs/devel/qapi-code-gen.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index 138921b386..2cd51729c3 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -786,8 +786,8 @@ Configuring the schema
 Syntax::
 
     COND = STRING
-         | { 'all: [ COND, ... ] }
-         | { 'any: [ COND, ... ] }
+         | { 'all': [ COND, ... ] }
+         | { 'any': [ COND, ... ] }
          | { 'not': COND }
 
 All definitions take an optional 'if' member.  Its value must be a
-- 
2.49.0

[PATCH 3/3] docs/devel/qapi-code-gen: Update cross-reference syntax

[Markus Armbruster]

The new QAPI code generator creates a cross-reference target for each
definition documentation.  Enabled for the QEMU QMP Reference manual
in commit a377f39f38f, and for the QEMU Storage Daemon QMP Reference
Manual and the QEMU Guest Agent Protocol Reference in commit
a6af5443440.  We've put these targets to use since, but neglected to
update doc comment markup documentation.  Do that now.

Co-developed-by: John Snow <jsnow@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 docs/devel/qapi-code-gen.rst | 11 ++++++++---
 docs/devel/qapi-domain.rst   |  1 +
 2 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index 2cd51729c3..d97602f464 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -943,9 +943,14 @@ The usual ****strong****, *\*emphasized\** and ````literal```` markup
 should be used.  If you need a single literal ``*``, you will need to
 backslash-escape it.
 
-Use ``@foo`` to reference a name in the schema.  This is an rST
-extension.  It is rendered the same way as ````foo````, but carries
-additional meaning.
+Use ```foo``` to reference a definition in the schema.  This generates
+a link to the definition.  In the event that such a cross-reference is
+ambiguous, you can use `QAPI cross-reference roles
+<QAPI-domain-cross-references>` to disambiguate.
+
+Use @foo to reference a member description within the current
+definition.  This is an rST extension.  It is currently rendered the
+same way as ````foo````, but carries additional meaning.
 
 Example::
 
diff --git a/docs/devel/qapi-domain.rst b/docs/devel/qapi-domain.rst
index fe540d1e40..1924f12d42 100644
--- a/docs/devel/qapi-domain.rst
+++ b/docs/devel/qapi-domain.rst
@@ -375,6 +375,7 @@ Will allow you to add arbitrary field lists in QAPI directives::
 
       :see also: Lorem ipsum, dolor sit amet ...
 
+.. _QAPI-domain-cross-references:
 
 Cross-references
 ================
-- 
2.49.0

Re: [PATCH 1/3] docs/devel/qapi-code-gen: Add two cross-references we missed

[John Snow]

On Thu, Jul 31, 2025 at 1:40 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> Missed in commit 9c66762a601 (docs/qapi-code-gen: add
> cross-references).
>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

Reviewed-by: John Snow <jsnow@redhat.com>

> ---
>  docs/devel/qapi-code-gen.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
> index dfdbeac5a5..138921b386 100644
> --- a/docs/devel/qapi-code-gen.rst
> +++ b/docs/devel/qapi-code-gen.rst
> @@ -646,9 +646,9 @@ Member 'event' names the event.  This is the event name used in the
>  Client JSON Protocol.
>
>  Member 'data' defines the event-specific data.  It defaults to an
> -empty MEMBERS object.
> +empty MEMBERS_ object.

Admittedly, I forgot this was valid syntax - it's core to
restructuredtext and not a sphinxism, so it only works within the
scope of a single document. Quite suitable for this use case, just
slightly ashamed I didn't recognize it immediately.

>
> -If 'data' is a MEMBERS object, then MEMBERS defines event-specific
> +If 'data' is a MEMBERS_ object, then MEMBERS defines event-specific
>  data just like a struct type's 'data' defines struct type members.
>
>  If 'data' is a STRING, then STRING names a complex type whose members
> --
> 2.49.0
>

Re: [PATCH 2/3] docs/devel/qapi-code-gen: Fix typos in QAPI schema language grammar

[John Snow]

On Thu, Jul 31, 2025 at 1:40 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> Fixes: 3248c1aaf2db (docs: update the documentation upfront about schema configuration)
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

Reviewed-by: John Snow <jsnow@redhat.com>

> ---
>  docs/devel/qapi-code-gen.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
> index 138921b386..2cd51729c3 100644
> --- a/docs/devel/qapi-code-gen.rst
> +++ b/docs/devel/qapi-code-gen.rst
> @@ -786,8 +786,8 @@ Configuring the schema
>  Syntax::
>
>      COND = STRING
> -         | { 'all: [ COND, ... ] }
> -         | { 'any: [ COND, ... ] }
> +         | { 'all': [ COND, ... ] }
> +         | { 'any': [ COND, ... ] }

Oopsie.

>           | { 'not': COND }
>
>  All definitions take an optional 'if' member.  Its value must be a
> --
> 2.49.0
>

Re: [PATCH 3/3] docs/devel/qapi-code-gen: Update cross-reference syntax

[John Snow]

On Thu, Jul 31, 2025 at 1:40 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> The new QAPI code generator creates a cross-reference target for each
> definition documentation.  Enabled for the QEMU QMP Reference manual
> in commit a377f39f38f, and for the QEMU Storage Daemon QMP Reference
> Manual and the QEMU Guest Agent Protocol Reference in commit
> a6af5443440.  We've put these targets to use since, but neglected to
> update doc comment markup documentation.  Do that now.
>
> Co-developed-by: John Snow <jsnow@redhat.com>

No need for this in my opinion, the SOB suffices to say the same thing
in my book. I don't insist you remove it, just seems ... oddly
pretentious to say I "co-developed" a single paragraph of text ;)

> Signed-off-by: John Snow <jsnow@redhat.com>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

Reviewed-by: John Snow <jsnow@redhat.com>

> ---
>  docs/devel/qapi-code-gen.rst | 11 ++++++++---
>  docs/devel/qapi-domain.rst   |  1 +
>  2 files changed, 9 insertions(+), 3 deletions(-)
>
> diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
> index 2cd51729c3..d97602f464 100644
> --- a/docs/devel/qapi-code-gen.rst
> +++ b/docs/devel/qapi-code-gen.rst
> @@ -943,9 +943,14 @@ The usual ****strong****, *\*emphasized\** and ````literal```` markup
>  should be used.  If you need a single literal ``*``, you will need to
>  backslash-escape it.
>
> -Use ``@foo`` to reference a name in the schema.  This is an rST
> -extension.  It is rendered the same way as ````foo````, but carries
> -additional meaning.
> +Use ```foo``` to reference a definition in the schema.  This generates
> +a link to the definition.  In the event that such a cross-reference is
> +ambiguous, you can use `QAPI cross-reference roles
> +<QAPI-domain-cross-references>` to disambiguate.
> +
> +Use @foo to reference a member description within the current
> +definition.  This is an rST extension.  It is currently rendered the
> +same way as ````foo````, but carries additional meaning.
>
>  Example::
>
> diff --git a/docs/devel/qapi-domain.rst b/docs/devel/qapi-domain.rst
> index fe540d1e40..1924f12d42 100644
> --- a/docs/devel/qapi-domain.rst
> +++ b/docs/devel/qapi-domain.rst
> @@ -375,6 +375,7 @@ Will allow you to add arbitrary field lists in QAPI directives::
>
>        :see also: Lorem ipsum, dolor sit amet ...
>
> +.. _QAPI-domain-cross-references:
>
>  Cross-references
>  ================
> --
> 2.49.0
>

Re: [PATCH 3/3] docs/devel/qapi-code-gen: Update cross-reference syntax

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> On Thu, Jul 31, 2025 at 1:40 AM Markus Armbruster <armbru@redhat.com> wrote:
>>
>> The new QAPI code generator creates a cross-reference target for each
>> definition documentation.  Enabled for the QEMU QMP Reference manual
>> in commit a377f39f38f, and for the QEMU Storage Daemon QMP Reference
>> Manual and the QEMU Guest Agent Protocol Reference in commit
>> a6af5443440.  We've put these targets to use since, but neglected to
>> update doc comment markup documentation.  Do that now.
>>
>> Co-developed-by: John Snow <jsnow@redhat.com>
>
> No need for this in my opinion, the SOB suffices to say the same thing
> in my book. I don't insist you remove it, just seems ... oddly
> pretentious to say I "co-developed" a single paragraph of text ;)

It wasn't obvious to me how to best credit you, so I tried this.  The
Co-developed-by serves as an explanation why your S-o-b is there.

Please pick one:

1. Do nothing.

2. Delete Co-developed-by.

3. Delete Co-developed-by, your Signed-off-by, add your Reviewed-by.

>> Signed-off-by: John Snow <jsnow@redhat.com>
>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>
> Reviewed-by: John Snow <jsnow@redhat.com>

Thanks!

Re: [PATCH 3/3] docs/devel/qapi-code-gen: Update cross-reference syntax

[John Snow]

On Fri, Aug 8, 2025 at 2:35 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> John Snow <jsnow@redhat.com> writes:
>
> > On Thu, Jul 31, 2025 at 1:40 AM Markus Armbruster <armbru@redhat.com> wrote:
> >>
> >> The new QAPI code generator creates a cross-reference target for each
> >> definition documentation.  Enabled for the QEMU QMP Reference manual
> >> in commit a377f39f38f, and for the QEMU Storage Daemon QMP Reference
> >> Manual and the QEMU Guest Agent Protocol Reference in commit
> >> a6af5443440.  We've put these targets to use since, but neglected to
> >> update doc comment markup documentation.  Do that now.
> >>
> >> Co-developed-by: John Snow <jsnow@redhat.com>
> >
> > No need for this in my opinion, the SOB suffices to say the same thing
> > in my book. I don't insist you remove it, just seems ... oddly
> > pretentious to say I "co-developed" a single paragraph of text ;)
>
> It wasn't obvious to me how to best credit you, so I tried this.  The
> Co-developed-by serves as an explanation why your S-o-b is there.
>
> Please pick one:
>
> 1. Do nothing.

You're on vacation now, so by process of elimination, we'll do this ;)

>
> 2. Delete Co-developed-by.
>
> 3. Delete Co-developed-by, your Signed-off-by, add your Reviewed-by.
>
> >> Signed-off-by: John Snow <jsnow@redhat.com>
> >> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> >
> > Reviewed-by: John Snow <jsnow@redhat.com>
>
> Thanks!
>