diff --git a/lib/phoenix/socket.ex b/lib/phoenix/socket.ex
index ce7920c315..7963ef31e8 100644
--- a/lib/phoenix/socket.ex
+++ b/lib/phoenix/socket.ex
@@ -332,24 +332,32 @@ defmodule Phoenix.Socket do
   ## USER API
 
   @doc """
-  Adds key-value pairs to socket assigns.
+  Adds a `key`/`value` pair to `socket` assigns.
 
-  A single key-value pair may be passed, a keyword list or map
-  of assigns may be provided to be merged into existing socket
-  assigns.
+  See also `assign/2` to add multiple key/value pairs.
 
   ## Examples
 
       iex> assign(socket, :name, "Elixir")
-      iex> assign(socket, name: "Elixir", logo: "💧")
   """
   def assign(%Socket{} = socket, key, value) do
     assign(socket, [{key, value}])
   end
 
-  def assign(%Socket{} = socket, attrs)
-      when is_map(attrs) or is_list(attrs) do
-    %{socket | assigns: Map.merge(socket.assigns, Map.new(attrs))}
+  @doc """
+  Adds key/value pairs to socket assigns.
+
+  A keyword list or a map of assigns must be given as argument to be merged into existing assigns.
+
+  ## Examples
+
+      iex> assign(socket, name: "Elixir", logo: "💧")
+      iex> assign(socket, %{name: "Elixir"})
+
+  """
+  def assign(%Socket{} = socket, keyword_or_map)
+      when is_map(keyword_or_map) or is_list(keyword_or_map) do
+    %{socket | assigns: Map.merge(socket.assigns, Map.new(keyword_or_map))}
   end
 
   @doc """