Begin working on asyncio port.

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

docs/conf.py

@@ -32,12 +32,19 @@ sys.path.insert(0, os.path.abspath('..'))
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.extlinks',
+    'sphinx.ext.napoleon',
 ]
 
 extlinks = {
     'issue': ('https://github.com/Rapptz/discord.py/issues/%s', 'issue '),
 }
 
+rst_prolog = """
+.. |coro| replace:: This function is a |corourl|_.
+.. |corourl| replace:: *coroutine*
+.. _corourl: https://docs.python.org/3/library/asyncio-task.html#coroutine
+"""
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']