Add documentation warning about exceptions in coroutines

diff --git a/tornado/gen.py b/tornado/gen.py
index 4bb82d422c7b48ab7c654e3556861ab6414398cb..3d50e7cc49a253d3104dc9f53bdafa3452d96e65 100644 (file)
--- a/tornado/gen.py
+++ b/tornado/gen.py
@@ -136,6 +136,17 @@ def coroutine(func, replace_callback=True):
 
     From the caller's perspective, ``@gen.coroutine`` is similar to
     the combination of ``@return_future`` and ``@gen.engine``.
+
+    .. warning::
+
+       When exceptions occur inside a coroutine, the exception
+       information will be stored in the `.Future` object. You must
+       examine the result of the `.Future` object, or the exception
+       may go unnoticed by your code. This means yielding the function
+       if called from another coroutine, using something like
+       `.IOLoop.run_sync` for top-level calls, or passing the `.Future`
+       to `.IOLoop.add_future`.
+
     """
     return _make_coroutine_wrapper(func, replace_callback=True)