Clarify comments per review

Author: minrk

jupyter_client/blocking/client.py

@@ -36,11 +36,12 @@ def wait_for_ready(self, timeout=None):
 
         from ..manager import KernelManager
         if not isinstance(self.parent, KernelManager):
-            # We aren't connected to a manager,
-            # so first wait for kernel to become responsive to heartbeats
+            # This Client was not created by a KernelManager,
+            # so wait for kernel to become responsive to heartbeats
+            # before checking for kernel_info reply
             while not self.is_alive():
                 if time.time() > abs_timeout:
-                    raise RuntimeError("Kernel didn't respond to heartbeats in %d seconds" % timeout)
+                    raise RuntimeError("Kernel didn't respond to heartbeats in %d seconds and timed out" % timeout)
                 time.sleep(0.2)
 
         # Wait for kernel info reply on shell channel

jupyter_client/client.py

@@ -183,7 +183,8 @@ def is_alive(self):
         """Is the kernel process still running?"""
         from .manager import KernelManager
         if isinstance(self.parent, KernelManager):
-            # We were created by a KernelManager, we can ask them:
+            # This KernelClient was created by a KernelManager,
+            # we can ask the parent KernelManager:
             return self.parent.is_alive()
         if self._hb_channel is not None:
             # We don't have access to the KernelManager,

jupyter_client/tests/signalkernel.py

@@ -64,5 +64,7 @@ def init_io(self):
         pass # disable stdout/stderr capture
 
 if __name__ == '__main__':
+    # make startup artificially slow,
+    # so that we exercise client logic for slow-starting kernels
     time.sleep(2)
     SignalTestApp.launch_instance()