Specify return values of stream functions (phoenixframework#3196)

lib/phoenix_live_view.ex

@@ -1541,6 +1541,7 @@ defmodule Phoenix.LiveView do
 
   @doc ~S"""
   Assigns a new stream to the socket or inserts items into an existing stream.
+  Returns an updated `socket`.
 
   Streams are a mechanism for managing large collections on the client without
   keeping the resources on the server.
@@ -1657,6 +1658,7 @@ defmodule Phoenix.LiveView do
   Now `stream_insert/3` and `stream_delete/3` may be issued and new rows will
   be inserted or deleted from the client.
   """
+  @spec stream(%Socket{}, name :: atom | String.t, items :: Enumerable.t, opts :: Keyword.t) :: %Socket{}
   def stream(%Socket{} = socket, name, items, opts \\ []) do
     if Keyword.has_key?(opts, :dom_id) do
       IO.warn(
@@ -1697,7 +1699,10 @@ defmodule Phoenix.LiveView do
       def update(assigns, socket) do
         {:ok, stream(socket, :songs, ...)}
       end
+
+  Returns an updated `socket`.
   """
+  @spec stream_configure(%Socket{}, name :: atom | String.t, opts :: Keyword.t) :: %Socket{}
   def stream_configure(%Socket{} = socket, name, opts) when is_list(opts) do
     new_socket = ensure_streams(socket)
 
@@ -1724,6 +1729,8 @@ defmodule Phoenix.LiveView do
   @doc """
   Inserts a new item or updates an existing item in the stream.
 
+  Returns an updated `socket`.
+
   By default, the item is appended to the parent DOM container.
   The `:at` option may be provided to insert or update an item
   to a particular index in the collection on the client.
@@ -1765,6 +1772,7 @@ defmodule Phoenix.LiveView do
 
   See `stream_delete/3` for more information on deleting items.
   """
+  @spec stream_insert(%Socket{}, name :: atom | String.t, item :: any, opts :: Keyword.t) :: %Socket{}
   def stream_insert(%Socket{} = socket, name, item, opts \\ []) do
     at = Keyword.get(opts, :at, -1)
     limit = Keyword.get(opts, :limit)
@@ -1789,14 +1797,19 @@ defmodule Phoenix.LiveView do
 
   See `stream_delete_by_dom_id/3` to remove an item without requiring the
   original data structure.
+
+  Returns an updated `socket`.
   """
+  @spec stream_delete(%Socket{}, name :: atom | String.t, item :: any) :: %Socket{}
   def stream_delete(%Socket{} = socket, name, item) do
     update_stream(socket, name, &LiveStream.delete_item(&1, item))
   end
 
   @doc ~S'''
   Deletes an item from the stream given its computed DOM id.
 
+  Returns an updated `socket`.
+
   Behaves just like `stream_delete/3`, but accept the precomputed DOM id,
   which allows deleting from a stream without fetching or building the original
   stream data structure.
@@ -1823,6 +1836,7 @@ defmodule Phoenix.LiveView do
         {:noreply, stream_delete_by_dom_id(socket, :songs, dom_id)}
       end
   '''
+  @spec stream_delete_by_dom_id(%Socket{}, name :: atom | String.t, id :: String.t) :: %Socket{}
   def stream_delete_by_dom_id(%Socket{} = socket, name, id) do
     update_stream(socket, name, &LiveStream.delete_item_by_dom_id(&1, id))
   end