Better document {:error, reason}

lib/phoenix/socket/transport.ex

@@ -136,10 +136,12 @@ defmodule Phoenix.Socket.Transport do
   Connects to the socket.
 
   The transport passes a map of metadata and the socket
-  returns `{:ok, state}`. `{:error, reason}` or `:error`. 
-  The state must be stored by the transport and returned 
-  in all future operations. `{:error, reason}` can only 
-  be used with websockets.
+  returns `{:ok, state}`, `{:error, reason}` or `:error`.
+  The state must be stored by the transport and returned
+  in all future operations. When `{:error, reason}` is
+  returned, some transports - such as WebSockets - allow
+  customizing the response based on `reason` via a custom
+  `:error_handler`.
 
   This function is used for authorization purposes and it
   may be invoked outside of the process that effectively
@@ -494,7 +496,7 @@ defmodule Phoenix.Socket.Transport do
          conn = put_in(conn.secret_key_base, endpoint.config(:secret_key_base)),
          {_, session} <- store.get(conn, cookie, init),
          csrf_state when is_binary(csrf_state) <-
-          Plug.CSRFProtection.dump_state_from_session(session[csrf_token_key]),
+           Plug.CSRFProtection.dump_state_from_session(session[csrf_token_key]),
          true <- Plug.CSRFProtection.valid_state_and_csrf_token?(csrf_state, csrf_token) do
       session
     else

lib/phoenix/transports/long_poll_server.ex

@@ -16,6 +16,7 @@ defmodule Phoenix.Transports.LongPoll.Server do
       params: params,
       connect_info: connect_info
     }
+
     window_ms = Keyword.fetch!(options, :window_ms)
 
     case handler.connect(config) do
@@ -75,6 +76,7 @@ defmodule Phoenix.Transports.LongPoll.Server do
     case state.buffer do
       [] ->
         {:noreply, %{state | client_ref: {client_ref, ref}, last_client_poll: now_ms()}}
+
       buffer ->
         broadcast_from!(state, client_ref, {:messages, Enum.reverse(buffer), ref})
         {:noreply, %{state | client_ref: nil, last_client_poll: now_ms(), buffer: []}}
@@ -116,12 +118,16 @@ defmodule Phoenix.Transports.LongPoll.Server do
 
   defp broadcast_from!(state, client_ref, msg) when is_binary(client_ref),
     do: PubSub.broadcast_from!(state.pubsub_server, self(), client_ref, msg)
+
   defp broadcast_from!(_state, client_ref, msg) when is_pid(client_ref),
     do: send(client_ref, msg)
 
   defp publish_reply(state, reply) when is_map(reply) do
-    IO.warn "Returning a map from the LongPolling serializer is deprecated. " <>
-            "Please return JSON encoded data instead (see Phoenix.Socket.Serializer)"
+    IO.warn(
+      "Returning a map from the LongPolling serializer is deprecated. " <>
+        "Please return JSON encoded data instead (see Phoenix.Socket.Serializer)"
+    )
+
     publish_reply(state, Phoenix.json_library().encode_to_iodata!(reply))
   end