Document Phoenix.Socket callbacks. Closes #1252

lib/phoenix/socket.ex

@@ -79,8 +79,40 @@ defmodule Phoenix.Socket do
   use Behaviour
   alias Phoenix.Socket
 
+
+  @doc """
+  Receives the socket params and authenticates the connection.
+
+  ## Socket params and assigns
+
+  Socket params are passed from the client and can
+  be used to verify and authenticate a user. After
+  verification, you can put default assigns into
+  the socket that will be set for all channels, ie
+
+      {:ok, assign(socket, :user_id, verified_user_id)}
+
+  To deny connection, return `:error`.
+
+  See `Phoenix.Token` documentation for examples in
+  performing token verification on connect.
+  """
   defcallback connect(params :: map, Socket.t) :: {:ok, Socket.t} | :error
 
+  @doc ~S"""
+  Identifies the socket connection.
+
+  Socket id's are topics that allow you to identify all sockets for a given user:
+
+      def id(socket), do: "users_socket:#{socket.assigns.user_id}"
+
+  Would allow you to broadcast a "disconnect" event and terminate
+  all active sockets and channels for a given user:
+
+      MyApp.Endpoint.broadcast("users_socket:" <> user.id, "disconnect", %{})
+
+  Returning `nil` makes this socket anonymous.
+  """
   defcallback id(Socket.t) :: String.t | nil
 
   defmodule InvalidMessageError do
@@ -275,4 +307,3 @@ defmodule Phoenix.Socket do
     end)
   end
 end
-