Deprecate debug parameter of make_handler()

- Deprecate `debug` parameter of `Application.make_handler`
- Add docs for `debug` parameter in the `Application`'s constructor
- Fix docs display for `Application`'s `loop` parameter
- Add docs for `Application.debug` attribute
- Add a note about the deprecation of the `debug` parameter for
    `Application.make_handler()`

aiohttp/web.py

@@ -221,6 +221,21 @@ def middlewares(self):
         return self._middlewares
 
     def make_handler(self, **kwargs):
+        try:
+            debug = kwargs['debug']
+        except KeyError:
+            pass
+        else:
+            if debug != self.debug:
+                raise ValueError(
+                    "The value of `debug` parameter conflicts with the debug "
+                    "settings of the Application instance. The settings of "
+                    "the application will be used instead of the passed "
+                    "parameter. For more information please check "
+                    "http://aiohttp.readthedocs.io/en/stable/"
+                    "web_reference.html#aiohttp.web.Application"
+                )
+        kwargs['debug'] = self.debug
         return self._handler_factory(
             self, self.router, loop=self.loop, **kwargs)
 

docs/web_reference.rst

@@ -1026,16 +1026,16 @@ Although :class:`Application` is a :obj:`dict`-like object, it can't be
 duplicated like one using :meth:`Application.copy`.
 
 .. class:: Application(*, loop=None, router=None, logger=<default>, \
-                       middlewares=(), **kwargs)
+                       middlewares=(), debug=False, **kwargs)
 
    The class inherits :class:`dict`.
 
    :param loop: :ref:`event loop<asyncio-event-loop>` used
-                for processing HTTP requests.
+    for processing HTTP requests.
 
-                If param is ``None`` :func:`asyncio.get_event_loop`
-                used for getting default event loop, but we strongly
-                recommend to use explicit loops everywhere.
+    If param is ``None`` :func:`asyncio.get_event_loop`
+    used for getting default event loop, but we strongly
+    recommend to use explicit loops everywhere.
 
    :param router: :class:`aiohttp.abc.AbstractRouter` instance, the system
                   creates :class:`UrlDispatcher` by default if
@@ -1048,6 +1048,8 @@ duplicated like one using :meth:`Application.copy`.
    :param middlewares: :class:`list` of middleware factories, see
                        :ref:`aiohttp-web-middlewares` for details.
 
+   :param debug: Switches debug mode.
+
    .. attribute:: router
 
       Read-only property that returns *router instance*.
@@ -1060,6 +1062,11 @@ duplicated like one using :meth:`Application.copy`.
 
       :ref:`event loop<asyncio-event-loop>` used for processing HTTP requests.
 
+
+   .. attribute:: debug
+
+      Boolean value indicating whether the debug mode is turned on or off.
+
    .. attribute:: on_response_prepare
 
       A :class:`~aiohttp.signals.Signal` that is fired at the beginning
@@ -1128,6 +1135,11 @@ duplicated like one using :meth:`Application.copy`.
       :param kwargs: additional parameters for :class:`RequestHandlerFactory`
                      constructor.
 
+      .. note::
+        You should not pass ``debug`` parameter within ``kwargs`` since
+        its usage in  :meth:`Application.make_handler` is deprecated in favour
+        of :attr:`Application.debug`.
+
       You should pass result of the method as *protocol_factory* to
       :meth:`~asyncio.AbstractEventLoop.create_server`, e.g.::