From 2f3b9cea39df3b23a7f374680268ea9598074bc4 Mon Sep 17 00:00:00 2001
From: Andrew Svetlov <andrew.svetlov@gmail.com>
Date: Tue, 7 Nov 2017 12:08:53 +0300
Subject: [PATCH] Update FAQ (#2471)

* Update FAQ

* Mention aiohttp 2.3
---
 docs/faq.rst | 31 +++++++++++++++++++++++--------
 docs/web.rst |  3 +++
 2 files changed, 26 insertions(+), 8 deletions(-)

diff --git a/docs/faq.rst b/docs/faq.rst
index 84ffcdcfcb8..b9de9cb9b9a 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -1,18 +1,33 @@
-Frequently Asked Questions
-==========================
+FAQ
+===
+
 .. contents::
    :local:
 
 Are there any plans for @app.route decorator like in Flask?
 -----------------------------------------------------------
-There are couple issues here:
 
-* This adds huge problem name "configuration as side effect of importing".
-* Route matching is order specific, it is very hard to maintain import order.
-* In semi large application better to have routes table defined in one place.
+We have it already (*aiohttp>=2.3* required):
+:ref:`aiohttp-web-alternative-routes-definition`.
+
+The difference is: ``@app.route`` should have an ``app`` in module
+global namespace, which makes *circular import hell* easy.
+
+*aiohttp* provides a :class:`~aiohttp.web.RouteTableDef` decoupled
+ from an application instance::
+
+   routes = web.RouteTableDef()
+
+   @routes.get('/get')
+   async def handle_get(request):
+       ...
+
+
+   @routes.post('/post')
+   async def handle_post(request):
+       ...
 
-For this reason feature will not be implemented. But if you really want to
-use decorators just derive from web.Application and add desired method.
+   app.router.add_routes(routes)
 
 
 Has aiohttp the Flask Blueprint or Django App concept?
diff --git a/docs/web.rst b/docs/web.rst
index 89b59cec30e..83b1f42150b 100644
--- a/docs/web.rst
+++ b/docs/web.rst
@@ -320,6 +320,9 @@ viewed using the :meth:`UrlDispatcher.named_resources` method::
    :meth:`UrlDispatcher.resources` instead of
    :meth:`UrlDispatcher.named_routes` / :meth:`UrlDispatcher.routes`.
 
+
+.. _aiohttp-web-alternative-routes-definition:
+
 Alternative ways for registering routes
 ---------------------------------------