add temporary annotations in AsyncRunner, run and sleep_handler

sardine_core/handlers/sleep_handler/__init__.py

@@ -57,6 +57,8 @@ async def sleep_until(self, deadline: NUMBER) -> None:
 
         The deadline is based on the fish bowl clock's time.
         """
+
+        # General checks
         if self.env is None:
             raise ValueError("SleepHandler must be added to a fish bowl")
         elif not self.env.is_running():
@@ -120,6 +122,7 @@ def _check_running(self):
             self._poll_task.cancel()
 
     def _create_handle(self, deadline: NUMBER) -> TimeHandle:
+        #TODO: document this function
         handle = TimeHandle(deadline)
 
         if self.env.clock.time >= deadline:

sardine_core/run.py

@@ -212,6 +212,8 @@ def swim(
     """
 
     def decorator(func: Union[Callable, AsyncRunner], /) -> AsyncRunner:
+
+        # This is true when the function is already running on the scheduler
         if isinstance(func, AsyncRunner):
             func.update_state(*args, **kwargs)
             bowl.scheduler.start_runner(func)
@@ -220,15 +222,18 @@ def decorator(func: Union[Callable, AsyncRunner], /) -> AsyncRunner:
         if until is not None:
             func = for_(until)(func)
 
+        # Checks if the runner already exists, otherwise, create a new one
         runner = bowl.scheduler.get_runner(func.__name__)
         if runner is None:
             runner = AsyncRunner(func.__name__)
+            # Some AsyncRunners need to stay in the background and never be
+            # interrupted by any user action (c.f. Tidal Vortex Loop)
             if background_job:
                 runner.background_job = True
         elif not runner.is_running():
-            # Runner has likely stopped swimming, in which case
-            # we should make sure the old state doesn't pollute
-            # the new function when it's pushed
+            # Runner has likely stopped swimming, in which case we should
+            # make sure the old state doesn't pollute the new function
+            # when it's pushed
             runner.reset_states()
 
         # Runners normally allow the same functions to appear in the stack,
@@ -238,14 +243,16 @@ def decorator(func: Union[Callable, AsyncRunner], /) -> AsyncRunner:
             bowl.scheduler.start_runner(runner)
             return runner
 
+        # We apply the 'quant' policy (start now, on next beat, bar, etc)
         deadline = get_deadline_from_quant(bowl.clock, quant)
+        # Deadline is None when the 'quant' policy is now
         if deadline is None:
             runner.push(func, *args, **kwargs)
         else:
             runner.push_deferred(deadline, func, *args, **kwargs)
 
-        # Intentionally avoid interval correction so
-        # the user doesn't accidentally nudge the runner
+        # Intentionally avoid interval correction so the user doesn't 
+        # accidentally nudge the runner
         runner.swim()
         runner.reload()
 
@@ -398,12 +405,8 @@ def panic(*runners: AsyncRunner) -> None:
 
 
 def Pat(
-    pattern: str,
-    i: int = 0,
-    div: int = 1,
-    rate: int = 1,
-    as_text: bool = False
-    ) -> Any:
+    pattern: str, i: int = 0, div: int = 1, rate: int = 1, as_text: bool = False
+) -> Any:
     """
     General purpose pattern interface. This function can be used to summon the global
     parser stored in the fish_bowl. It is generally used to pattern outside of the