Update state transition comment for Task

Author: kristjanvalur

Lib/asyncio/tasks.py

@@ -73,15 +73,23 @@ 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.
+    # - 2 (_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 only transition from 1 to 2 is through __wakeup().  __wakeup()
+    # leaves _fut_waiter in place.
+    # In state 1, one of the callbacks of __fut_waiter must be __wakeup().
+    # It transitions from 2 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