Improve docs

docs/client_reference.rst

@@ -119,13 +119,15 @@ The client session supports the context manager protocol for self closing.
       forbidden, but you may modify the object in-place if needed.
 
 
-   .. coroutinemethod:: request(method, url, *, params=None, data=None,\
-                                headers=None, skip_auto_headers=None, \
-                                auth=None, allow_redirects=True,\
-                                max_redirects=10, encoding='utf-8',\
-                                version=HttpVersion(major=1, minor=1),\
-                                compress=None, chunked=None, expect100=False,\
-                                read_until_eof=True)
+   .. comethod:: request(method, url, *, params=None, data=None,\
+                         headers=None, skip_auto_headers=None, \
+                         auth=None, allow_redirects=True,\
+                         max_redirects=10, encoding='utf-8',\
+                         version=HttpVersion(major=1, minor=1),\
+                         compress=None, chunked=None, expect100=False,\
+                         read_until_eof=True)
+      :async-with:
+      :coroutine:
 
       Performs an asynchronous HTTP request. Returns a response object.
 
@@ -191,7 +193,9 @@ The client session supports the context manager protocol for self closing.
       :return ClientResponse: a :class:`client response
                               <ClientResponse>` object.
 
-   .. coroutinemethod:: get(url, *, allow_redirects=True, **kwargs)
+   .. comethod:: get(url, *, allow_redirects=True, **kwargs)
+      :async-with:
+      :coroutine:
 
       Perform a ``GET`` request.
 
@@ -207,7 +211,9 @@ The client session supports the context manager protocol for self closing.
       :return ClientResponse: a :class:`client response
                               <ClientResponse>` object.
 
-   .. coroutinemethod:: post(url, *, data=None, **kwargs)
+   .. comethod:: post(url, *, data=None, **kwargs)
+      :async-with:
+      :coroutine:
 
       Perform a ``POST`` request.
 
@@ -224,7 +230,9 @@ The client session supports the context manager protocol for self closing.
       :return ClientResponse: a :class:`client response
                               <ClientResponse>` object.
 
-   .. coroutinemethod:: put(url, *, data=None, **kwargs)
+   .. comethod:: put(url, *, data=None, **kwargs)
+      :async-with:
+      :coroutine:
 
       Perform a ``PUT`` request.
 
@@ -241,7 +249,9 @@ The client session supports the context manager protocol for self closing.
       :return ClientResponse: a :class:`client response
                               <ClientResponse>` object.
 
-   .. coroutinemethod:: delete(url, **kwargs)
+   .. comethod:: delete(url, **kwargs)
+      :async-with:
+      :coroutine:
 
       Perform a ``DELETE`` request.
 
@@ -254,7 +264,9 @@ The client session supports the context manager protocol for self closing.
       :return ClientResponse: a :class:`client response
                               <ClientResponse>` object.
 
-   .. coroutinemethod:: head(url, *, allow_redirects=False, **kwargs)
+   .. comethod:: head(url, *, allow_redirects=False, **kwargs)
+      :async-with:
+      :coroutine:
 
       Perform a ``HEAD`` request.
 
@@ -270,7 +282,9 @@ The client session supports the context manager protocol for self closing.
       :return ClientResponse: a :class:`client response
                               <ClientResponse>` object.
 
-   .. coroutinemethod:: options(url, *, allow_redirects=True, **kwargs)
+   .. comethod:: options(url, *, allow_redirects=True, **kwargs)
+      :async-with:
+      :coroutine:
 
       Perform an ``OPTIONS`` request.
 
@@ -287,7 +301,9 @@ The client session supports the context manager protocol for self closing.
       :return ClientResponse: a :class:`client response
                               <ClientResponse>` object.
 
-   .. coroutinemethod:: patch(url, *, data=None, **kwargs)
+   .. comethod:: patch(url, *, data=None, **kwargs)
+      :async-with:
+      :coroutine:
 
       Perform a ``PATCH`` request.
 
@@ -304,11 +320,13 @@ The client session supports the context manager protocol for self closing.
       :return ClientResponse: a :class:`client response
                               <ClientResponse>` object.
 
-   .. coroutinemethod:: ws_connect(url, *, protocols=(), timeout=10.0,\
-                                   auth=None,\
-                                   autoclose=True,\
-                                   autoping=True,\
-                                   origin=None)
+   .. comethod:: ws_connect(url, *, protocols=(), timeout=10.0,\
+                            auth=None,\
+                            autoclose=True,\
+                            autoping=True,\
+                            origin=None)
+      :async-with:
+      :coroutine:
 
       Create a websocket connection. Returns a
       :class:`ClientWebSocketResponse` object.
@@ -343,7 +361,7 @@ The client session supports the context manager protocol for self closing.
 
          Add *origin* parameter.
 
-   .. coroutinemethod:: close()
+   .. comethod:: close()
 
       Close underlying connector.
 
@@ -715,7 +733,7 @@ BaseConnector
 
       .. versionadded:: 0.16
 
-   .. coroutinemethod:: close()
+   .. comethod:: close()
 
       Close all opened connections.
 
@@ -725,7 +743,7 @@ BaseConnector
          returns a future for keeping backward compatibility during
          transition period).
 
-   .. coroutinemethod:: connect(request)
+   .. comethod:: connect(request)
 
       Get a free connection from pool or create new one if connection
       is absent in the pool.
@@ -739,7 +757,7 @@ BaseConnector
 
       :return: :class:`Connection` object.
 
-   .. coroutinemethod:: _create_connection(req)
+   .. comethod:: _create_connection(req)
 
       Abstract method for actual connection establishing, should be
       overridden in subclasses.
@@ -1111,7 +1129,7 @@ Response object
 
       For :term:`keep-alive` support see :meth:`release`.
 
-   .. coroutinemethod:: read()
+   .. comethod:: read()
 
       Read the whole response's body as :class:`bytes`.
 
@@ -1122,13 +1140,13 @@ Response object
 
       .. seealso:: :meth:`close`, :meth:`release`.
 
-   .. coroutinemethod:: release()
+   .. comethod:: release()
 
       Finish response processing, release underlying connection and
       return it into free connection pool for re-usage by next upcoming
       request.
 
-   .. coroutinemethod:: text(encoding=None)
+   .. comethod:: text(encoding=None)
 
       Read response's body and return decoded :class:`str` using
       specified *encoding* parameter.
@@ -1146,7 +1164,7 @@ Response object
 
       :return str: decoded *BODY*
 
-   .. coroutinemethod:: json(encoding=None, loads=json.loads)
+   .. comethod:: json(encoding=None, loads=json.loads)
 
       Read response's body as *JSON*, return :class:`dict` using
       specified *encoding* and *loader*.
@@ -1222,7 +1240,7 @@ manually.
       :raise TypeError: if data is not :class:`bytes`,
                         :class:`bytearray` or :class:`memoryview`.
 
-   .. coroutinemethod:: close(*, code=1000, message=b'')
+   .. comethod:: close(*, code=1000, message=b'')
 
       A :ref:`coroutine<coroutine>` that initiates closing handshake by sending
       :const:`~aiohttp.websocket.MSG_CLOSE` message. It waits for
@@ -1235,7 +1253,7 @@ manually.
                       :class:`str` (converted to *UTF-8* encoded bytes)
                       or :class:`bytes`.
 
-   .. coroutinemethod:: receive()
+   .. comethod:: receive()
 
       A :ref:`coroutine<coroutine>` that waits upcoming *data*
       message from peer and returns it.