gh-109955 : Update state transition comments for asyncio.Task

Lib/asyncio/tasks.py

@@ -73,15 +73,27 @@ class Task(futures._PyFuture):  # Inherit Python Task implementation
     """A coroutine wrapped in a Future."""
 
     # An important invariant maintained while a Task not done:
+    # _fut_waiter is either None or a Future.  The task can be
+    # in any of 3 states:
     #
-    # - Either _fut_waiter is None, and _step() is scheduled;
-    # - or _fut_waiter is some Future, and _step() is *not* scheduled.
+    # - 1 (_fut_waiter is not None and not _fut_waiter.done());
+    #   __step() is *not* scheduled and the Task is waiting for _fut_waiter.
+    # - 2a (_fut_waiter is None or _fut_waiter.done()), and __wakeup() is scheduled;
+    #   the Task is waiting for __wakeup() to be executed.
+    # - 2b (_fut_waiter is None or _fut_waiter.done()), and __step() is scheduled;
+    #   the Task is waiting for __step() to be executed.
+    # - 3 _fut_waiter is None and __step() is *not* scheduled;
+    #   the Task is currently executing (in __step()).
     #
-    # The only transition from the latter to the former is through
-    # _wakeup().  When _fut_waiter is not None, one of its callbacks
-    # must be _wakeup().
-
-    # If False, don't log a message if the task is destroyed whereas its
+    # The transition from 1 to 2a happens when _fut_waiter becomes done(),
+    # as it schedules __wakeup() to be called.
+    # The transition from 2a to 2b happens when __wakeup() is executed,
+    # scheduling __step() to be called, leaving _fut_waiter in place.
+    # In state 1, one of the callbacks of __fut_waiter must be __wakeup().
+    # It transitions from 2b to 3 when __step() is executed, and it clears
+    # _fut_waiter to None.
+
+    # If False, don't log a message if the task is destroyed while its
     # status is still pending
     _log_destroy_pending = True