1 files changed, 19 insertions, 2 deletions
diff --git a/docs/api.rst b/docs/api.rst
index 935f05dc..1e0bdd62 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -34,17 +34,34 @@ overriding the specific events. For example: ::
     import discord
 
     class MyClient(discord.Client):
+
+        @asyncio.coroutine
         def on_message(self, message):
-            self.send_message(message.channel, 'Hello World!')
+            yield from self.send_message(message.channel, 'Hello World!')
 
 
 If an event handler raises an exception, :func:`on_error` will be called
 to handle it, which defaults to print a traceback and ignore the exception.
 
+.. warning::
+
+    All the events must be a |corourl|_. If they aren't, then you might get unexpected
+    errors. In order to turn a function into a coroutine they must either be decorated
+    with ``@asyncio.coroutine`` or in Python 3.5+ be defined using the ``async def``
+    declaration.
+
+    The following two functions are examples of coroutine functions: ::
+
+        async def on_ready():
+            pass
+
+        @asyncio.coroutine
+        def on_ready():
+            pass
+
 .. versionadded:: 0.7.0
     Subclassing to listen to events.
 
-
 .. function:: on_ready()
 
     Called when the client is done preparing the data received from Discord. Usually after login is successful