Should event metadata be in attribute docstrings?

Currently, the data types for events are nicely integrated with VS Code and other tooling:

But this is not the case for events themselves. A lot of the key information is in comments like this:

https://github.com/openedx/openedx-events/blob/34d3fce371f14c892d77284f9fcba8a5e67fc544/openedx_events/content_authoring/signals.py#L251-L261

Which does not appear in relevant places in VS Code:

However, if we were to update our approach to put this data into "attribute docstrings" (as defined in PEP 257), then this information would show up in VS Code (as well as other tools like mkdocstrings):

😎

The code I used for the above screenshot looks like this:

CONTENT_OBJECT_TAGS_CHANGED = OpenEdxPublicSignal(
    event_type="org.openedx.content_authoring.content.object.tags.changed.v1",
    data={
        "content_object": ContentObjectData,
    }
)
"""
Emitted when an object's tags are changed.

**Warning**: This is DEPRECATED; please use `CONTENT_OBJECT_ASSOCIATIONS_CHANGED` instead.

Details |:
-|-
event_type | `org.openedx.content_authoring.content.object.tags.changed.v1`
event_name | `CONTENT_OBJECT_TAGS_CHANGED`
event_data | `content_object`: `ContentObjectData`
"""

Such attribute docstrings are not normally accessible at runtime (same as with the current comment approach), but you can use the griffe module to access them.

Start with openedx_events/content_authoring/signals.py, especially the event definition around lines 251–261, and review how OpenEdxPublicSignal events currently document their metadata. Convert the relevant event metadata comments to PEP 257 attribute docstrings, then verify that the descriptions and metadata appear in VS Code and are accessible to mkdocstrings via griffe.