From 13b4d19ced4430a777a0ab9d08bda86b3fd01fca Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Thu, 31 Jul 2025 07:40:42 +0200 Subject: docs/devel/qapi-code-gen: Add two cross-references we missed Missed in commit 9c66762a601 (docs/qapi-code-gen: add cross-references). Signed-off-by: Markus Armbruster Message-ID: <20250731054044.4011789-2-armbru@redhat.com> Reviewed-by: John Snow --- docs/devel/qapi-code-gen.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index dfdbeac..138921b 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 -- cgit v1.1 From 60e847dcf06aa4cc41cf7535d5ea4b1f5b34a616 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Thu, 31 Jul 2025 07:40:43 +0200 Subject: docs/devel/qapi-code-gen: Fix typos in QAPI schema language grammar Fixes: 3248c1aaf2db (docs: update the documentation upfront about schema configuration) Signed-off-by: Markus Armbruster Message-ID: <20250731054044.4011789-3-armbru@redhat.com> Reviewed-by: John Snow --- docs/devel/qapi-code-gen.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 138921b..2cd5172 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 -- cgit v1.1 From 79f57adce686d0027608af4be363cde2409e5740 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Thu, 31 Jul 2025 07:40:44 +0200 Subject: docs/devel/qapi-code-gen: Update cross-reference syntax 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 Signed-off-by: John Snow Signed-off-by: Markus Armbruster Message-ID: <20250731054044.4011789-4-armbru@redhat.com> --- docs/devel/qapi-code-gen.rst | 11 ++++++++--- docs/devel/qapi-domain.rst | 1 + 2 files changed, 9 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 2cd5172..d97602f 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 +` 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 fe540d1..1924f12 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 ================ -- cgit v1.1