Work on docs

aiohttp/web_urldispatcher.py

@@ -263,6 +263,11 @@ def method(self):
     def handler(self):
         return self._handler
 
+    @property
+    @abc.abstractmethod
+    def name(self):
+        """Optional route's name, always equals to resource's name."""
+
     @property
     def resource(self):
         return self._resource

docs/web_reference.rst

@@ -1509,67 +1509,80 @@ Route classes hierarhy::
        StaticRoute
        SystemRoute
 
-User should not instantiate route classes by hand but can give *named
-route instance* by ``router[name]`` if he have added route by
-:meth:`UrlDispatcher.add_route` or :meth:`UrlDispatcher.add_static`
-calls with non-empty *name* parameter.
+:class:`ResourceRoute` is the route used for new-style resources,
+:class:`PlainRoute` and :class:`DynamicRoute` serves old-style
+routes kept for backward compatibility only.
 
+:class:`StaticRoute` is used for static file serving
+(:meth:`UrlDispatcher.add_static`).  Don't rely on the route
+implementation too hard, static file handling most likely will be
+rewritten eventually.
 
-There are three concrete route classes:
+:class:`SystemRoute` exists for representing errors when requested url
+is not found or requested http method is not supported.  It's very
+deep implementation details for now actually.
 
-* :class:`PlainRoute` for urls without :ref:`variable
-  pathes<aiohttp-web-variable-handler>` spec.
+So the only non-deprecated and not internal route is
+:class:`ResourceRoute` only.
 
-* :class:`DynamicRoute` for urls with :ref:`variable
-  pathes<aiohttp-web-variable-handler>` spec.
-
-* :class:`StaticRoute` for static file handlers.
-
-.. class:: Route
+.. class:: AbstractRoute
 
    Base class for routes served by :class:`UrlDispatcher`.
 
    .. attribute:: method
 
-   HTTP method handled by the route, e.g. *GET*, *POST* etc.
+      HTTP method handled by the route, e.g. *GET*, *POST* etc.
 
    .. attribute:: handler
 
-   :ref:`handler<aiohttp-web-handler>` that processes the route.
+      :ref:`handler<aiohttp-web-handler>` that processes the route.
 
    .. attribute:: name
 
-   Name of the route.
+      Name of the route, always equals to name of resource which owns the route.
+
+   .. attribute:: resource
+
+      Resource instance which holds the route.
 
    .. method:: match(path)
 
-   Abstract method, accepts *URL path* and returns :class:`dict` with
-   parsed *path parts* for :class:`UrlMappingMatchInfo` or ``None`` if
-   the route cannot handle given *path*.
+      Abstract method, accepts *URL path* and returns :class:`dict`
+      with parsed *path parts* for :class:`UrlMappingMatchInfo` or
+      ``None`` if the route cannot handle given *path*.
 
-   The method exists for internal usage, end user unlikely need to call it.
+      The method exists for internal usage, end user unlikely need to
+      call it.
 
    .. method:: url(*, query=None, **kwargs)
 
-   Abstract method for constructing url handled by the route.
+      Abstract method for constructing url handled by the route.
+
+      *query* is a mapping or list of *(name, value)* pairs for
+      specifying *query* part of url (parameter is processed by
+      :func:`~urllib.parse.urlencode`).
+
+      Other available parameters depends on concrete route class and
+      described in descendant classes.
+
+   .. coroutinemethod:: handle_expect_header(request)
 
-   *query* is a mapping or list of *(name, value)* pairs for
-   specifying *query* part of url (parameter is processed by
-   :func:`~urllib.parse.urlencode`).
+      ``100-continue`` handler.
 
-   Other available parameters depends on concrete route class and
-   described in descendant classes.
+.. class:: ResourceRoute
+
+   The route class for handling different HTTP methods for :class:`Resource`.
 
 .. class:: PlainRoute
 
    The route class for handling plain *URL path*, e.g. ``"/a/b/c"``
 
    .. method:: url(*, parts, query=None)
 
-   Construct url, doesn't accepts extra parameters::
+       Construct url, doesn't accepts extra parameters::
 
-      >>> route.url(query={'d': 1, 'e': 2})
-      '/a/b/c/?d=1&e=2'
+          >>> route.url(query={'d': 1, 'e': 2})
+          '/a/b/c/?d=1&e=2'
 
 .. class:: DynamicRoute
 
@@ -1578,11 +1591,11 @@ There are three concrete route classes:
 
    .. method:: url(*, parts, query=None)
 
-   Construct url with given *dynamic parts*::
+      Construct url with given *dynamic parts*::
 
-       >>> route.url(parts={'name1': 'b', 'name2': 'c'},
-                     query={'d': 1, 'e': 2})
-       '/a/b/c/?d=1&e=2'
+          >>> route.url(parts={'name1': 'b', 'name2': 'c'},
+                        query={'d': 1, 'e': 2})
+          '/a/b/c/?d=1&e=2'
 
 
 .. class:: StaticRoute
@@ -1592,10 +1605,10 @@ There are three concrete route classes:
 
    .. method:: url(*, filename, query=None)
 
-   Construct url for given *filename*::
+      Construct url for given *filename*::
 
-      >>> route.url(filename='img/logo.png', query={'param': 1})
-      '/path/to/static/img/logo.png?param=1'
+         >>> route.url(filename='img/logo.png', query={'param': 1})
+         '/path/to/static/img/logo.png?param=1'
 
 
 .. class:: SystemRoute
@@ -1606,8 +1619,8 @@ There are three concrete route classes:
 
    .. method:: url()
 
-   Always raises :exc:`RuntimeError`, :class:`SystemRoute` should not
-   be used in url construction expressions.
+      Always raises :exc:`RuntimeError`, :class:`SystemRoute` should not
+      be used in url construction expressions.
 
 
 MatchInfo
@@ -1627,9 +1640,17 @@ In general the result may be any object derived from
    Inherited from :class:`dict` and :class:`AbstractMatchInfo`. Dict
    items are given from :meth:`Route.match` call return value.
 
+   .. attribute:: expect_handler
+
+      A coroutine for handling ``100-continue``.
+
+   .. attribute:: handler
+
+      A coroutine for handling request.
+
    .. attribute:: route
 
-   :class:`Route` instance for url matching.
+      :class:`Route` instance for url matching.
 
 
 View