From 7acdfc035e44cf2499122bc30caea38985bbf0b6 Mon Sep 17 00:00:00 2001
From: Laurens Valk <laurens@pybricks.com>
Date: Tue, 5 Mar 2024 15:00:03 +0100
Subject: [PATCH] pybricks.tools: Document run loop active check.

---
 src/pybricks/tools.py | 46 +++++++++++++++++++------------------------
 1 file changed, 20 insertions(+), 26 deletions(-)

diff --git a/src/pybricks/tools.py b/src/pybricks/tools.py
index 2abfdd6a..44acc07d 100644
--- a/src/pybricks/tools.py
+++ b/src/pybricks/tools.py
@@ -26,8 +26,7 @@ class StopWatch:
     """A stopwatch to measure time intervals. Similar to the stopwatch
     feature on your phone."""
 
-    def __init__(self):
-        ...
+    def __init__(self): ...
 
     def time(self) -> int:
         """time() -> int: ms
@@ -108,38 +107,27 @@ class Matrix:
 
     A :class:`.Matrix` object is immutable."""
 
-    def __add__(self, other) -> Matrix:
-        ...
+    def __add__(self, other) -> Matrix: ...
 
-    def __iadd__(self, other) -> Matrix:
-        ...
+    def __iadd__(self, other) -> Matrix: ...
 
-    def __sub__(self, other) -> Matrix:
-        ...
+    def __sub__(self, other) -> Matrix: ...
 
-    def __isub__(self, other) -> Matrix:
-        ...
+    def __isub__(self, other) -> Matrix: ...
 
-    def __mul__(self, other) -> Matrix:
-        ...
+    def __mul__(self, other) -> Matrix: ...
 
-    def __rmul__(self, other) -> Matrix:
-        ...
+    def __rmul__(self, other) -> Matrix: ...
 
-    def __imul__(self, other) -> Matrix:
-        ...
+    def __imul__(self, other) -> Matrix: ...
 
-    def __truediv__(self, other) -> Matrix:
-        ...
+    def __truediv__(self, other) -> Matrix: ...
 
-    def __itruediv__(self, other) -> Matrix:
-        ...
+    def __itruediv__(self, other) -> Matrix: ...
 
-    def __floordiv__(self, other) -> Matrix:
-        ...
+    def __floordiv__(self, other) -> Matrix: ...
 
-    def __ifloordiv__(self, other) -> Matrix:
-        ...
+    def __ifloordiv__(self, other) -> Matrix: ...
 
     def __init__(self, rows: Sequence[Sequence[float]]):
         """Matrix(rows)
@@ -275,15 +263,21 @@ def multitask(*coroutines: Coroutine, race=False) -> MaybeAwaitableTuple:
     """
 
 
-def run_task(coroutine: Coroutine):
+def run_task(coroutine: Coroutine) -> Optional[bool]:
     """
-    run_task(coroutine)
+    run_task(coroutine) -> bool | None
 
     Runs a coroutine from start to finish while blocking the rest of the
     program. This is used primarily to run the main coroutine of a program.
 
+    Calls to this function are not allowed to be nested.
+
     Arguments:
         coroutine (coroutine): The main coroutine to run.
+
+    Returns:
+        If no ``coroutine`` is given, this function returns whether the
+        run loop is currently active (``True``) or not (``False``).
     """