Improve docs for IOLoop.add/remove_timeout()

diff --git a/tornado/ioloop.py b/tornado/ioloop.py
index ea34e0fe68e14b4fe67b6d6144ef57788f450117..666257c9955e5f743713da7dcc1cc3952265ca23 100644 (file)
--- a/tornado/ioloop.py
+++ b/tornado/ioloop.py
@@ -309,12 +309,19 @@ class IOLoop(object):
         return self._running
 
     def add_timeout(self, deadline, callback):
-        """Calls the given callback at the time deadline from the I/O loop."""
+        """Calls the given callback at the time deadline from the I/O loop.
+
+        Returns a handle that may be passed to remove_timeout to cancel.
+        """
         timeout = _Timeout(deadline, stack_context.wrap(callback))
         bisect.insort(self._timeouts, timeout)
         return timeout
 
     def remove_timeout(self, timeout):
+        """Cancels a pending timeout.
+
+        The argument is a handle as returned by add_timeout.
+        """
         self._timeouts.remove(timeout)
 
     def add_callback(self, callback):