Explain functionality more in the documentation

Signed-off-by: Mathias L. Baumann <[email protected]>

Author: Marenz

src/frequenz/dispatch/__init__.py

@@ -15,7 +15,14 @@
 class Dispatcher:
     """A highlevel interface for the dispatch API.
 
-    This class provides a highlevel interface to the dispatch API. It
+    This class provides a highlevel interface to the dispatch API.
+    It provides two channels:
+
+    One that sends a dispatch event message whenever a dispatch is created, updated or deleted.
+
+    The other sends a dispatch message whenever a dispatch is ready to be
+    executed according to the schedule.
+
     allows to receive new dispatches and ready dispatches.
 
     Example:

src/frequenz/dispatch/actor.py

@@ -174,6 +174,10 @@ def _update_dispatch_schedule(
         Schedules, reschedules or cancels the dispatch based on the start_time
         and active status.
 
+        For example:
+            * when the start_time changes, the dispatch is rescheduled
+            * when the dispatch is deactivated, the dispatch is cancelled
+
         Args:
             dispatch: The dispatch to update the schedule for.
             old_dispatch: The old dispatch, if available.