From: Dustin Spicuzza <dustin@virtualroadside.com>
Date: Fri, 5 Sep 2014 15:57:15 +0000 (-0400)
Subject: Add documentation warning about exceptions in coroutines
X-Git-Tag: v4.1.0b1~89^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F1175%2Fhead;p=thirdparty%2Ftornado.git

Add documentation warning about exceptions in coroutines
---

diff --git a/tornado/gen.py b/tornado/gen.py
index 4bb82d422..3d50e7cc4 100644
--- 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)