Update comment on _get_deepest_tracable_frame

1 files changed, 11 insertions, 3 deletions

diff --git a/aergia/aergia.py b/aergia/aergia.py
index efc68e2..501a3ae 100755
--- a/aergia/aergia.py
+++ b/aergia/aergia.py
@@ -301,9 +301,17 @@ class Aergia(object):
     @staticmethod
     def _get_deepest_traceable_frame(coro):
         '''Get the deepest frame of coro we care to trace.
-        Since coro is a suspended task, we know that the frame we are
-        looking for belongs to a COROUTINE. Else, it cannot be the case
-        it is suspended.'''
+        Luckily for us, coroutines keep track of the coroutine object which
+        they are waiting on (cr_await). We simply need to trace that down as far
+        as possible to get the actual line we are waiting on.
+        Note that it cannot be the case that a task is not suspended in a frame
+        that does not belong to a coroutine, asyncio is very particular about
+        that!
+
+        If cr_await is None, then the task was created but never started.
+        (since once a task is started, it either starts waiting on another
+        coroutine, or finishes immediately). These cases were already filtered
+        out in `_get_idle_task_frames'.'''
         curr = coro
         deepest_frame = None
         while curr: