 
   After a client has successfully joined a channel, incoming events from the
   client are routed through the channel's `handle_in/3` callbacks. Within these
-  callbacks, you can perform any action. Typically you'll either forward a
-  message to all listeners with `broadcast!/3`, or push a message directly down
-  the socket with `push/3`. Incoming callbacks must return the `socket` to
-  maintain ephemeral state.
-
-  Here's an example of receiving an incoming `"new_msg"` event from one client,
-  and broadcasting the message to all topic subscribers for this socket.
+  callbacks, you can perform any action. Incoming callbacks must return the
+  `socket` to maintain ephemeral state.
+
+  Typically you'll either forward a message to all listeners with
+  `broadcast!/3` or reply directly to a client event for request/response style
+  messaging.
+
+  General message payloads are received as maps:
 
       def handle_in("new_msg", %{"uid" => uid, "body" => body}, socket) do
-        broadcast!(socket, "new_msg", %{uid: uid, body: body})
-        {:noreply, socket}
-      end
-
-  General message payloads are received as maps, and binary data payloads are
-  passed as a `{:binary, data}` tuple:
+        ...
+        {:reply, :ok, socket}
+      end
+
+  Binary data payloads are passed as a `{:binary, data}` tuple:
 
       def handle_in("file_chunk", {:binary, chunk}, socket) do
         ...
         {:reply, :ok, socket}
       end
 
-  You can also push a message directly down the socket, in the form of a map,
-  or a tagged `{:binary, data}` tuple:
-
-      # client asks for their current rank, push sent directly as a new event.
-      def handle_in("current_rank", _, socket) do
-        push(socket, "current_rank", %{val: Game.get_rank(socket.assigns[:user])})
-        push(socket, "photo", {:binary, File.read!(socket.assigns.photo_path)})
+  ## Broadcasts
+ 
+  Here's an example of receiving an incoming `"new_msg"` event from one client,
+  and broadcasting the message to all topic subscribers for this socket.
+
+      def handle_in("new_msg", %{"uid" => uid, "body" => body}, socket) do
+        broadcast!(socket, "new_msg", %{uid: uid, body: body})
         {:noreply, socket}
       end
 
   ## Replies
 
-  In addition to pushing messages out when you receive a `handle_in` event,
-  you can also reply directly to a client event for request/response style
-  messaging. This is useful when a client must know the result of an operation
-  or to simply ack messages.
+  Replies are useful for acknowledging a client's message or responding with
+  the results of an operation. A reply is sent only to the client connected to
+  the current channel process. Behind the scenes, they include the client
+  message `ref`, which allows the client to correlate the reply it receives
+  with the message it sent.
 
   For example, imagine creating a resource and replying with the created record:
 

  @doc """
  Replies asynchronously to a socket push.

  Useful when you need to reply to a push that can't otherwise be handled using
  the `{:reply, {status, payload}, socket}` return from your `handle_in`
  callbacks. `reply/2` will be used in the rare cases you need to perform work in
  another process and reply when finished by generating a reference to the push
  with `socket_ref/1`.

  *Note*: In such cases, a `socket_ref` should be generated and
  passed to the external process, so the `socket` itself is not leaked outside
  the channel. The `socket` holds information such as assigns and transport
  configuration, so it's important to not copy this information outside of the
  channel that owns it.

  ## Examples


  end

  @doc """
  Sends an event directly to the connected client without requiring a prior
  message from the client.

  The event's message must be a serializable map or a tagged `{:binary, data}`
  tuple where `data` is binary data.

  Note that unlike some in client libraries, this server-side `push/3` does not
  return a reference. If you need to get a reply from the client and to
  correlate that reply with the message you pushed, you'll need to include a
  unique identifier in the message, track it in the Channel's state, have the
  client include it in its reply, and examine the ref when the reply comes to
  `handle_in/3`.

  ## Examples

