From 524669e2d9698d89adea556bf114c3d4f375180d Mon Sep 17 00:00:00 2001
From: Vitalie Maldur <maldur.vitalik@gmail.com>
Date: Sat, 23 Jul 2016 18:49:46 +0200
Subject: [PATCH] Fix for (#976): add documentation for websocket send_json and
 receive_json

---
 docs/client_reference.rst | 51 +++++++++++++++++++++++++++++++++++++++
 docs/web_reference.rst    | 16 ++++++++++++
 2 files changed, 67 insertions(+)

diff --git a/docs/client_reference.rst b/docs/client_reference.rst
index 3c0e59da6ba..172042ed7cf 100644
--- a/docs/client_reference.rst
+++ b/docs/client_reference.rst
@@ -1255,6 +1255,22 @@ manually.
       :raise TypeError: if data is not :class:`bytes`,
                         :class:`bytearray` or :class:`memoryview`.
 
+   .. method:: send_json(data, *, dumps=json.loads)
+
+      Send *data* to peer as JSON string.
+
+      :param data: data to send.
+
+      :param callable dumps: any :term:`callable` that accepts an object and
+                             returns a JSON string
+                             (:func:`json.dumps` by default).
+
+      :raise RuntimeError: if connection is not started or closing
+
+      :raise ValueError: if data is not serializable object
+
+      :raise TypeError: if value returned by :term:`dumps` is not :class:`str`
+
    .. comethod:: close(*, code=1000, message=b'')
 
       A :ref:`coroutine<coroutine>` that initiates closing handshake by sending
@@ -1284,6 +1300,41 @@ manually.
       :return: :class:`~aiohttp.websocket.Message`, `tp` is types of
          `~aiohttp.MsgType`
 
+   .. coroutinemethod:: receive_str()
+
+      A :ref:`coroutine<coroutine>` that calls :meth:`receive` but
+      also asserts the message type is
+      :const:`~aiohttp.websocket.MSG_TEXT`.
+
+      :return str: peer's message content.
+
+      :raise TypeError: if message is :const:`~aiohttp.websocket.MSG_BINARY`.
+
+   .. coroutinemethod:: receive_bytes()
+
+      A :ref:`coroutine<coroutine>` that calls :meth:`receive` but
+      also asserts the message type is
+      :const:`~aiohttp.websocket.MSG_BINARY`.
+
+      :return bytes: peer's message content.
+
+      :raise TypeError: if message is :const:`~aiohttp.websocket.MSG_TEXT`.
+
+   .. coroutinemethod:: receive_json(*, loads=json.loads)
+
+      A :ref:`coroutine<coroutine>` that calls :meth:`receive`, asserts the
+      message type is :const:`~aiohttp.websocket.MSG_TEXT`, and loads the JSON
+      string to a Python dict.
+
+      :param callable loads: any :term:`callable` that accepts
+                              :class:`str` and returns :class:`dict`
+                              with parsed JSON (:func:`json.loads` by
+                              default).
+
+      :return dict: loaded JSON content
+
+      :raise TypeError: if message is :const:`~aiohttp.websocket.MSG_BINARY`.
+      :raise ValueError: if message is not valid JSON.
 
 Utilities
 ---------
diff --git a/docs/web_reference.rst b/docs/web_reference.rst
index 79368a98f73..8b9fa6da275 100644
--- a/docs/web_reference.rst
+++ b/docs/web_reference.rst
@@ -825,6 +825,22 @@ WebSocketResponse
       :raise TypeError: if data is not :class:`bytes`,
                         :class:`bytearray` or :class:`memoryview`.
 
+   .. method:: send_json(data, *, dumps=json.loads)
+
+      Send *data* to peer as JSON string.
+
+      :param data: data to send.
+
+      :param callable dumps: any :term:`callable` that accepts an object and
+                             returns a JSON string
+                             (:func:`json.dumps` by default).
+
+      :raise RuntimeError: if connection is not started or closing
+
+      :raise ValueError: if data is not serializable object
+
+      :raise TypeError: if value returned by :term:`dumps` is not :class:`str`
+
    .. coroutinemethod:: close(*, code=1000, message=b'')
 
       A :ref:`coroutine<coroutine>` that initiates closing