Should event metadata be in attribute docstrings?

[bradenmacdonald]

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:

openedx-events/openedx_events/content_authoring/signals.py

Lines 251 to 261 in 34d3fce

	# .. event_type: org.openedx.content_authoring.content.object.tags.changed.v1
	# .. event_name: CONTENT_OBJECT_TAGS_CHANGED
	# .. event_description: Emitted when an object's tags are changed.
	# .. event_data: ContentObjectData
	# .. event_warning: **DEPRECATED** please use CONTENT_OBJECT_ASSOCIATIONS_CHANGED instead.
	CONTENT_OBJECT_TAGS_CHANGED = OpenEdxPublicSignal(
	event_type="org.openedx.content_authoring.content.object.tags.changed.v1",
	data={
	"content_object": ContentObjectData,
	}
	)

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.

[kdmccormick]

I think attribute docstrings are a good idea 👍🏻

That said, where is this syntax from?

Details |:
-|-
event_type |  ...

The .. event_type: .. syntax that event annotations use now is from the openedx/code-annotations repo. It's language-agnostic, it's also used to annotate Open edX toggles and PII, and it complies to rST. It's not an industry standard, but it's at least simple and consistent within Open edX.

If we're adopting a new syntax, I think I'd like if it were widely adopted and also suitable for all the current code-annotations use cases.

[bradenmacdonald]

@kdmccormick It's just markdown table syntax, because it's easily parseable and looks nice in the Markdown renderer. Since .. event_type: .. is something we made up, VS Code doesn't recognize it as Markdown or rST, and it looks worse. We could still use it though, especially if you can find a way to get it to appear nicely?