Updated gen docs.

doc/gen.rst

@@ -4,12 +4,12 @@ Generator-based asynchronous interface
 ``tornadio2.gen`` module is a wrapper around ``tornado.gen`` API. You might want to take a
 look at Tornado documentation for this module, which can be `found here <http://www.tornadoweb.org/documentation/gen.html>`_.
 
-In most of the cases, it is not very convenient to use Tornado ``engine()``, because it makes your code truly
-asynchronous. For example, if client sends two packets: A and B, and if it takes some time for A to handle, B will be executed
-out of order.
+While you can use ``tornado.gen`` API without any problems in TornadIO, sometimes you may want to handle your messages in
+order they were received. If you will decorate your functions with ``tornado.gen.engine``, your will work asynchronously -
+second message might get handled before first message got data from the database.
 
 To prevent this situation, TornadIO2 provides helpful decorator: ``tornadio2.gen.sync_engine``. ``sync_engine`` will queue incoming
-calls if there's another instance of the function running. So, as a result, it will call your method synchronously without
+calls if there's another instance of the function running. As a result, it will call your method synchronously without
 blocking the io_loop. This decorator only works with class methods, don't try to use it for functions - it requires ``self``
 to properly function.
 
@@ -26,15 +26,15 @@ Lets check following example:
             self.send(response.body)
 
 If client will quickly send two messages, it will work "synchronously" - ``on_message`` won't be called for second message
-till handling of first message is finished.
+till handling of first message is finished, but it won't block ``io_loop``.
 
 However, if you will change decorator to ``gen.engine``, message handling will be asynchronous and might be out of order:
 ::
 
     from tornadio2 import gen
 
     class MyConnection(SocketConnection):
-        @gen.sync_engine
+        @gen.engine
         def on_message(self, query):
             http_client = AsyncHTTPClient()
             response = yield gen.Task(http_client.fetch, 'http://google.com?q=' + query)