docs: add documentation for in-line code annotations (#432)

docs/how-tos/creating-new-events.rst

@@ -111,25 +111,13 @@ specifies:
 
 The definition created in this step must comply with:
 
-- It should be created in the `signals.py` file in the corresponding subdomain. Refer to Naming Conventions ADR for more
+- It should be created in the ``signals.py`` file in the corresponding subdomain. Refer to Naming Conventions ADR for more
   on events subdomains.
-- It should follow the naming conventions specified in Naming Conventions ADR.
-- It must be documented using in-line documentation with at least: `event_type`, `event_name`, `event_description` and
-  `event_data`:
+- It should follow the naming conventions specified in :doc:`../decisions/0002-events-naming-and-versioning`.
+- It must be documented using in-line documentation with at least: ``event_type``, ``event_name``, ``event_description`` and
+  ``event_data``. See :doc:`../reference/in-line-code-annotations-for-an-event` for more information.
 
-+-------------------+----------------------------------------------------------------------------------------------------+
-| Annotation        | Description                                                                                        |
-+===================+====================================================================================================+
-| event_type        | Identifier across services of the event. Should follow the events naming conventions.              |
-+-------------------+----------------------------------------------------------------------------------------------------+
-| event_name        | Name of the variable storing the event instance.                                                   |
-+-------------------+----------------------------------------------------------------------------------------------------+
-| event_description | General description which includes when the event should be emitted.                               |
-+-------------------+----------------------------------------------------------------------------------------------------+
-| event_data        | What type of class attribute the event sends.                                                      |
-+-------------------+----------------------------------------------------------------------------------------------------+
-
-Consider the following example:
+Consider the course enrollment created event as an example:
 
 .. code-block:: python
 

docs/reference/in-line-code-annotations-for-an-event.rst

@@ -0,0 +1,34 @@
+In-line Code Annotations for An Open edX Event
+==============================================
+
+When creating a new Open edX Event, you must document the event definition using in-line code annotations. These annotations provide a structured way to document the event's metadata, making it easier for developers to understand the event's purpose and how it should be used.
+
++----------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
+| Annotation                       | Description                                                                                                                      |
++==================================+==================================================================================================================================+
+| event_type (Required)            | Identifier across services of the event. Should follow the :doc:`../decisions/0002-events-naming-and-versioning` standard.       |
++----------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
+| event_name (Required)            | Name of the variable storing the event instance.                                                                                 |
++----------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
+| event_description (Required)     | General description which includes when the event should be emitted.                                                             |
++----------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
+| event_data (Required)            | What type of class attribute the event sends.                                                                                    |
++----------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
+| event_warnings (Optional)        | Any warnings or considerations that should be taken into account when using the event.                                           |
++----------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
+
+Consider the following example:
+
+.. code-block:: python
+
+    # Location openedx_events/learning/signals.py
+    # .. event_type: org.openedx.learning.course.enrollment.created.v1
+    # .. event_name: COURSE_ENROLLMENT_CREATED
+    # .. event_description: emitted when the user's enrollment process is completed.
+    # .. event_data: CourseEnrollmentData
+    COURSE_ENROLLMENT_CREATED = OpenEdxPublicSignal(
+        event_type="org.openedx.learning.course.enrollment.created.v1",
+        data={
+            "enrollment": CourseEnrollmentData,
+        }
+    )

docs/reference/index.rst

@@ -6,6 +6,7 @@ References
    :caption: Contents:
 
    events
+   in-line-code-annotations-for-an-event
    glossary
    event-bus-configurations
    oeps