docs: add more detailed documentation under the concepts section

docs/concepts/events-vs-filters.rst

@@ -2,61 +2,79 @@ Events vs Filters
 =================
 
 Open edX Events and Filters are two types of hooks that allow developers to
-extend the functionality of the platform. They are defined in the
+extend the functionality of the Open edX platform. They are defined in the
 `openedx-events`_ and `openedx-filters`_ libraries respectively.
 
+.. _openedx-events: https://github.com/openedx/openedx-events
+.. _openedx-filters: https://github.com/openedx/openedx-filters
+
 Events
 ------
 
-Events are signals sent in specific places in the Open edX project core. They
-allow external functions to be executed when the event is triggered. These
-functions can extend the functionality of the platform or perform additional
+Events are Open edX specific Django signals sent in specific places in the Open edX
+platform. They allow external functions, known as signal handlers in the Django world,
+to be executed when the event is triggered. These functions can extend the functionality of the platform or perform additional
 processing based on the event data.
 
-Events are defined using the `OpenEdxPublicSignal` class, which provides a
-structured way to define the data and metadata associated with the event. This
-allows developers to create custom events for specific actions or changes within
-the platform.
+For a more detailed explanation of Open edX Events, see the `Open edX Events`_ document.
 
 Filters
 -------
 
 Filters are functions that can modify the behavior of the application by
-altering the data or parameters passed to a specific function or method. They
-allow developers to intercept and modify the input or output of a function
-without directly modifying the function itself.
+altering input data or halting execution based on specific conditions. They
+allow developers to implement application flow control based on their business
+login or requirements without directly modifying the application code.
 
-Filters are defined using the `OpenEdxFilter` class, which provides a way to
-define the filter function and the parameters it should receive. This allows
-developers to create custom filters that can be applied to specific functions or
-methods in the platform.
+For a more detailed explanation of Open edX Filters, see the `Open edX Filters`_ documentation.
 
 Differences between Events and Filters
 --------------------------------------
 
 Here are some key differences between Open edX Events and Filters:
 
-+----------------------+-------------------------------------------------------+-------------------------------------------------------------+
-|                      | Events                                                | Filters                                                     |
-+======================+=======================================================+=============================================================+
-| Purpose              | Trigger custom actions or processing in response to   | Modify the behavior of the application by intercepting and  |
-|                      | specific events or actions within the platform,       | altering the data or parameters passed to a specific        |
-|                      | without affecting the application's flow.             | function or method.                                         |
-+----------------------+-------------------------------------------------------+-------------------------------------------------------------+
-| Usage                | Used to execute external functions when an event is   | Used to intercept and modify the input or output of a       |
-|                      | triggered.                                            | component without directly modifying the component itself.  |
-+----------------------+-------------------------------------------------------+-------------------------------------------------------------+
-| Definition           | Defined using the `OpenEdxPublicSignal` class, which  | Defined using the `OpenEdxFilter` class, which provides a   |
-|                      | provides a structured way to define the data and      | way to define the filter function and the parameters it     |
-|                      | metadata associated with the event.                   | should receive.                                             |
-+----------------------+-------------------------------------------------------+-------------------------------------------------------------+
-| Implementation       | Implemented using Django signals, which allow         | Implemented by intercepting the input or output of a        |
-|                      | developers to send and receive notifications within   | function or method using the filter function.               |
-|                      | a Django application.                                 |                                                             |
-+----------------------+-------------------------------------------------------+-------------------------------------------------------------+
-| Example              | A custom event that triggers an email notification    | A filter that modifies the data returned by a specific      |
-|                      | when a user enrolls in a course.                      | API endpoint to include additional information.             |
-+----------------------+-------------------------------------------------------+-------------------------------------------------------------+
++-----------------+------------------------------------------------------------------------+-------------------------------------------------------------+-----+
+|                 | Events                                                                 | Filters                                                     |     |
++=================+========================================================================+=============================================================+=====+
+|| Purpose        || Trigger custom actions or processing in response to                   || Modify the behavior of the application by intercepting and ||    |
+||                || specific events or actions within the platform,                       || altering the data or parameters passed to a specific       ||    |
+||                || without affecting the application's flow.                             || function or method.                                        ||    |
++-----------------+------------------------------------------------------------------------+-------------------------------------------------------------+-----+
+|| Usage          || Used to **extend** functionality via signal handlers when an event is || Used to intercept and **modify** the input or output of a  ||    |
+||                || triggered.                                                            || component without directly modifying the component itself. ||    |
++-----------------+------------------------------------------------------------------------+-------------------------------------------------------------+-----+
+|| Definition     || Defined using the `OpenEdxPublicSignal` class, which                  || Defined using the `OpenEdxFilter` class, which provides a  ||    |
+||                || provides a structured way to define the data and                      || way to define the filter function and the parameters it    ||    |
+||                || metadata associated with the event.                                   || should receive.                                            ||    |
++-----------------+------------------------------------------------------------------------+-------------------------------------------------------------+-----+
+|| Implementation || Implemented using Django signals, which allow                         || Implemented using an accumulative pipeline mechanism which ||    |
+||                || developers to send and receive notifications within                   || takes a set of arguments and returns a modified set of     ||    |
+||                || a Django application.                                                 || arguments to the caller or raises exceptions during        ||    |
+||                ||                                                                       || processing.                                                ||    |
++-----------------+------------------------------------------------------------------------+-------------------------------------------------------------+-----+
+|| Example        || A custom event that triggers an email notification                    || A filter that modifies the data returned by a specific     ||    |
+||                || when a user enrolls in a course.                                      || API endpoint to include additional information.            ||    |
++-----------------+------------------------------------------------------------------------+-------------------------------------------------------------+-----+
 
 When to use an Open edX Event?
 ------------------------------
+
+Use an Open edX Event when you need to:
+
+- Trigger custom actions or processing in response to specific events or actions within the platform.
+- Communicate or coordinate with other components or services based on specific events or actions.
+- Synchronize data between different services or systems in response to specific events or actions.
+- Notify users or external systems about specific events or actions within the platform.
+- Integrate with external systems or services based on specific events or actions within the platform.
+
+When to use an Open edX Filter?
+-------------------------------
+
+Use an Open edX Filter when:
+
+- Modify the input or output of a specific function or method without directly modifying the function itself.
+- Intercept and modify the data or parameters passed to a specific component or service.
+- Apply a series of transformations or validations to the input or output of a specific function or method.
+- Enforce specific constraints or business rules on the input or output of a specific function or method.
+- Handle exceptions or errors that occur during the processing of a specific function or method.
+- Apply a set of filters to the input or output of a specific function or method based on specific conditions or criteria.

docs/concepts/hooks-extension-framework.rst

@@ -12,7 +12,7 @@ Open edX platform.
 Hooks: Open edX Events and Filters
 ----------------------------------
 
-Hooks are predefined places in the Open edX project core where externally defined
+Hooks are predefined places in the Open edX platform where externally defined
 functions can take place. These functions may alter what the user
 sees or experiences on the platform, while in other cases, they are purely informative. All
 hooks are designed to be extended through Open edX plugins and configurations.
@@ -32,8 +32,7 @@ The main goal of the framework is that developers can use them to change the
 functionality of the platform as needed and still be able to migrate to newer
 open releases with very little to no development effort, so they're designed
 with stability in mind, meaning that they are versioned and backward compatible
-as much as possible. In the case of the events, this approach is further
-detailed in the `versioning ADR`_ and the `payload ADR`_.
+as much as possible.
 
 A longer description of the framework and its history can be found in `OEP 50`_.
 

docs/concepts/openedx-events.rst

@@ -1,14 +1,11 @@
 Open edX Events
 ===============
 
-Overview
---------
-
 In the context of Open edX, events provide a mechanism for extending the platform
 by enabling developers to listen to specific Django signals emitted by various
 services and respond accordingly. This allows for customized reactions to key
 actions or changes within the platform, without requiring direct modifications
-to the core codebase.
+to the Open edX platform codebase.
 
 What are Open edX Events?
 -------------------------
@@ -18,26 +15,26 @@ when a specific action or event occurs. These signals are used to notify other
 services or components of the platform that an event has taken place, allowing them
 to respond accordingly. Events are defined using the ``OpenEdxPublicSignal`` class,
 which provides a structured way to define the data and metadata associated with
-the event.
+the event along with other relevant information.
 
 Why are Open edX Events important?
 ----------------------------------
 
 Open edX Events are a key component of the Hooks Extension Framework, which allows
 developers to extend the functionality of the platform in a stable and maintainable
-way. By defining events for specific actions or changes within the platform, developers
-can create custom listeners that respond to these events and perform additional
+way. By triggering events for specific actions or changes within the platform, developers
+can create event handlers that respond to these events and perform additional
 actions or processing as needed. This enables a wide range of use cases, from
 integrating with external systems to implementing custom business logic.
 
 How are Open edX Events used?
 -----------------------------
 
-Developers can create custom listeners for Open edX Events by defining signal
+Developers can create handlers for Open edX Events by implementing Django signal
 handlers that respond to specific events emitted by the platform. These signal
-handlers can be registered using Django's signal dispatcher, allowing them to
+handlers can be registered using Django's signal mechanism, allowing them to
 listen for events and execute custom logic in response. By defining events and
-listeners in this way, developers can create modular, reusable components that
+handlers in this way, developers can create modular, reusable components that
 extend the functionality of the platform without requiring direct modifications
 to the core codebase.
 
@@ -51,9 +48,9 @@ leverage their existing knowledge of Django signals.
 
 The lifecycle of an Open edX Event can be summarized as follows:
 
-1. A service emits an Open edX Event (Django signal) triggered by a specific action or event. The event data includes information about the event, such as the event name, timestamp, and any additional metadata.
+1. A service emits an Open edX Event (Open edX specific Django signal) triggered by a specific action or event. The event data includes information about the event, such as the event name, timestamp, and any additional metadata.
 2. Registered signal handlers listening for the event are called in response to the signal being emitted.
-3. The signal handler can perform additional processing or trigger other actions based on the event data.
+3. The signal handler performs additional processing or trigger other actions based on the event data.
 4. The event is considered complete once all registered signal handlers have executed.
 
 Here is an example of how that might look like with an existing event: