Adds the .. qapi:event:: directive, object, and :qapi:event:`name`
cross-referencing role.

Adds the :memb type name: field list syntax for documenting event data
members. As this syntax and phrasing will be shared with Structs and
Unions as well, add the field list definition to a shared abstract
class.

As per usual, QAPI cross-referencing for types in the member field list
will be added in a forthcoming commit.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 docs/sphinx/qapi_domain.py | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py
index d4120fa5ac6..d9c69af229d 100644
--- a/docs/sphinx/qapi_domain.py
+++ b/docs/sphinx/qapi_domain.py
@@ -337,6 +337,27 @@ class QAPIAlternate(QAPIObject):
     )
 
 
+class QAPIObjectWithMembers(QAPIObject):
+    """Base class for Events/Structs/Unions"""
+
+    doc_field_types = QAPIObject.doc_field_types.copy()
+    doc_field_types.extend(
+        [
+            # :member type name: descr
+            TypedField(
+                "member",
+                label=_("Members"),
+                names=("memb",),
+                can_collapse=False,
+            ),
+        ]
+    )
+
+
+class QAPIEvent(QAPIObjectWithMembers):
+    """Description of a QAPI Event."""
+
+
 class QAPIModule(SphinxDirective):
     """
     Directive to mark description of a new module.
@@ -499,6 +520,7 @@ class QAPIDomain(Domain):
     object_types: Dict[str, ObjType] = {
         "module": ObjType(_("module"), "mod", "any"),
         "command": ObjType(_("command"), "cmd", "any"),
+        "event": ObjType(_("event"), "event", "any"),
         "enum": ObjType(_("enum"), "enum", "type", "any"),
         "alternate": ObjType(_("alternate"), "alt", "type", "any"),
     }
@@ -508,6 +530,7 @@ class QAPIDomain(Domain):
     directives = {
         "module": QAPIModule,
         "command": QAPICommand,
+        "event": QAPIEvent,
         "enum": QAPIEnum,
         "alternate": QAPIAlternate,
     }
@@ -518,6 +541,7 @@ class QAPIDomain(Domain):
     roles = {
         "mod": QAPIXRefRole(),
         "cmd": QAPIXRefRole(),
+        "event": QAPIXRefRole(),
         "enum": QAPIXRefRole(),
         "alt": QAPIXRefRole(),
         # reference any data type (excludes modules, commands, events)
-- 
2.48.1

John Snow <jsnow@redhat.com> writes:

> Adds the .. qapi:event:: directive, object, and :qapi:event:`name`
> cross-referencing role.
>
> Adds the :memb type name: field list syntax for documenting event data
> members. As this syntax and phrasing will be shared with Structs and
> Unions as well, add the field list definition to a shared abstract
> class.

docs/devel/qapi-code-gen.rst calls it "event-specific data".  This is
quite a mouthful, so the code usually calls it "arguments".  Not least
because events are kind of like commands going in the other direction
(client to server), and the code dealing with them is often similar.

Both names make more sense to me than "member".  Hmm.  A rename could be
done as a follow-up if that's more convenient for you.

> As per usual, QAPI cross-referencing for types in the member field list
> will be added in a forthcoming commit.
>
> Signed-off-by: John Snow <jsnow@redhat.com>

On Fri, Mar 7, 2025 at 5:26 AM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
>
> > Adds the .. qapi:event:: directive, object, and :qapi:event:`name`
> > cross-referencing role.
> >
> > Adds the :memb type name: field list syntax for documenting event data
> > members. As this syntax and phrasing will be shared with Structs and
> > Unions as well, add the field list definition to a shared abstract
> > class.
>
> docs/devel/qapi-code-gen.rst calls it "event-specific data".  This is
> quite a mouthful, so the code usually calls it "arguments".  Not least
> because events are kind of like commands going in the other direction
> (client to server), and the code dealing with them is often similar.
>
> Both names make more sense to me than "member".  Hmm.  A rename could be
> done as a follow-up if that's more convenient for you.
>

Also wish you'd have said sooner :)

I might punt this one. At least, the next respin probably won't include
this.

I suppose I think about this in terms of "members of the event object."
Let's talk and fix later, changing the name outside of a gigantic series is
not difficult at all.


>
> > As per usual, QAPI cross-referencing for types in the member field list
> > will be added in a forthcoming commit.
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
>
>

John Snow <jsnow@redhat.com> writes:

> On Fri, Mar 7, 2025 at 5:26 AM Markus Armbruster <armbru@redhat.com> wrote:
>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > Adds the .. qapi:event:: directive, object, and :qapi:event:`name`
>> > cross-referencing role.
>> >
>> > Adds the :memb type name: field list syntax for documenting event data
>> > members. As this syntax and phrasing will be shared with Structs and
>> > Unions as well, add the field list definition to a shared abstract
>> > class.
>>
>> docs/devel/qapi-code-gen.rst calls it "event-specific data".  This is
>> quite a mouthful, so the code usually calls it "arguments".  Not least
>> because events are kind of like commands going in the other direction
>> (client to server), and the code dealing with them is often similar.
>>
>> Both names make more sense to me than "member".  Hmm.  A rename could be
>> done as a follow-up if that's more convenient for you.
>>
>
> Also wish you'd have said sooner :)

Fair again!

> I might punt this one. At least, the next respin probably won't include
> this.
>
> I suppose I think about this in terms of "members of the event object."
> Let's talk and fix later, changing the name outside of a gigantic series is
> not difficult at all.

Agree.

[...]