Add doc for add_head, update doc for add_get. (#1944)

* Add doc for add_head, update doc for add_get.

* Update CHANGES

CHANGES.rst

@@ -4,7 +4,7 @@ Changes
 2.2.0 (2017-xx-xx)
 ------------------
 
--
+- Add doc for add_head, update doc for add_get. #1944
 
 -
 

aiohttp/web_urldispatcher.py

@@ -845,13 +845,13 @@ def add_static(self, prefix, path, *, name=None, expect_handler=None,
         self.register_resource(resource)
         return resource
 
-    def add_head(self, *args, **kwargs):
+    def add_head(self, path, handler, **kwargs):
         """
         Shortcut for add_route with method HEAD
         """
-        return self.add_route(hdrs.METH_HEAD, *args, **kwargs)
+        return self.add_route(hdrs.METH_HEAD, path, handler, **kwargs)
 
-    def add_get(self, *args, name=None, allow_head=True, **kwargs):
+    def add_get(self, path, handler, *, name=None, allow_head=True, **kwargs):
         """
         Shortcut for add_route with method GET, if allow_head is true another
         route is added allowing head requests to the same endpoint
@@ -860,32 +860,34 @@ def add_get(self, *args, name=None, allow_head=True, **kwargs):
             # it name is not None append -head to avoid it conflicting with
             # the GET route below
             head_name = name and '{}-head'.format(name)
-            self.add_route(hdrs.METH_HEAD, *args, name=head_name, **kwargs)
-        return self.add_route(hdrs.METH_GET, *args, name=name, **kwargs)
+            self.add_route(hdrs.METH_HEAD, path, handler,
+                           name=head_name, **kwargs)
+        return self.add_route(hdrs.METH_GET, path, handler, name=name,
+                              **kwargs)
 
-    def add_post(self, *args, **kwargs):
+    def add_post(self, path, handler, **kwargs):
         """
         Shortcut for add_route with method POST
         """
-        return self.add_route(hdrs.METH_POST, *args, **kwargs)
+        return self.add_route(hdrs.METH_POST, path, handler, **kwargs)
 
-    def add_put(self, *args, **kwargs):
+    def add_put(self, path, handler, **kwargs):
         """
         Shortcut for add_route with method PUT
         """
-        return self.add_route(hdrs.METH_PUT, *args, **kwargs)
+        return self.add_route(hdrs.METH_PUT, path, handler, **kwargs)
 
-    def add_patch(self, *args, **kwargs):
+    def add_patch(self, path, handler, **kwargs):
         """
         Shortcut for add_route with method PATCH
         """
-        return self.add_route(hdrs.METH_PATCH, *args, **kwargs)
+        return self.add_route(hdrs.METH_PATCH, path, handler, **kwargs)
 
-    def add_delete(self, *args, **kwargs):
+    def add_delete(self, path, handler, **kwargs):
         """
         Shortcut for add_route with method DELETE
         """
-        return self.add_route(hdrs.METH_DELETE, *args, **kwargs)
+        return self.add_route(hdrs.METH_DELETE, path, handler, **kwargs)
 
     def freeze(self):
         super().freeze()

docs/web_reference.rst

@@ -1475,14 +1475,26 @@ Router is any object that implements :class:`AbstractRouter` interface.
 
       :returns: new :class:`PlainRoute` or :class:`DynamicRoute` instance.
 
-   .. method:: add_get(path, *args, **kwargs)
+   .. method:: add_get(path, handler, *, name=None, allow_head=True, **kwargs)
 
       Shortcut for adding a GET handler. Calls the :meth:`add_route` with \
       ``method`` equals to ``'GET'``.
 
+      If *allow_head* is ``True`` (default) the route for method HEAD
+      is added with the same handler as for GET.
+
+      If *name* is provided the name for HEAD route is suffixed with
+      ``'-head'``. For example ``router.add_get(path, handler,
+      name='route')`` call adds two routes: first for GET with name
+      ``'route'`` and second for HEAD with name ``'route-head'``.
+
       .. versionadded:: 1.0
 
-   .. method:: add_post(path, *args, **kwargs)
+      .. versionchanged:: 2.0
+
+         *allow_head* parameter added.
+
+   .. method:: add_post(path, handler, **kwargs)
 
       Shortcut for adding a POST handler. Calls the :meth:`add_route` with \
 
@@ -1491,21 +1503,28 @@ Router is any object that implements :class:`AbstractRouter` interface.
 
       .. versionadded:: 1.0
 
-   .. method:: add_put(path, *args, **kwargs)
+   .. method:: add_head(path, handler, **kwargs)
+
+      Shortcut for adding a HEAD handler. Calls the :meth:`add_route` with \
+      ``method`` equals to ``'HEAD'``.
+
+      .. versionadded:: 1.0
+
+   .. method:: add_put(path, handler, **kwargs)
 
       Shortcut for adding a PUT handler. Calls the :meth:`add_route` with \
       ``method`` equals to ``'PUT'``.
 
       .. versionadded:: 1.0
 
-   .. method:: add_patch(path, *args, **kwargs)
+   .. method:: add_patch(path, handler, **kwargs)
 
       Shortcut for adding a PATCH handler. Calls the :meth:`add_route` with \
       ``method`` equals to ``'PATCH'``.
 
       .. versionadded:: 1.0
 
-   .. method:: add_delete(path, *args, **kwargs)
+   .. method:: add_delete(path, handler, **kwargs)
 
       Shortcut for adding a DELETE handler. Calls the :meth:`add_route` with \
       ``method`` equals to ``'DELETE'``.