Merge pull request #238 from josevalim/patch-1

Do not use streams with async_request

lib/finch.ex

@@ -382,9 +382,11 @@ defmodule Finch do
   Sends an HTTP request asynchronously, returning a request reference.
 
   If the request is sent using HTTP1, an extra process is spawned to
-  consume messages from the underlying socket. If you wish to maximize
-  request rate, a strategy using `request/3` or `stream/5` should be
-  used to avoid this overhead.
+  consume messages from the underlying socket. The messages are sent
+  to the current process as soon as they arrive, as a firehose.  If
+  you wish to maximize request rate or have more control over how
+  messages are streamed, a strategy using `request/3` or `stream/5`
+  should be used instead.
 
   ## Receiving the response
 
@@ -411,26 +413,13 @@ defmodule Finch do
 
   ## Example
 
-      iex> Stream.resource(
-      ...>   fn ->
-      ...>     Finch.build(:get, "https://httpbin.org/stream/5")
-      ...>     |> Finch.async_request(MyFinch)
-      ...>   end,
-      ...>   fn ref ->
-      ...>     receive do
-      ...>       {^ref, :done} -> {:halt, ref}
-      ...>       {^ref, response} -> {[response], ref}
-      ...>     end
-      ...>   end,
-      ...>   fn _ref -> :ok end
-      ...> ) |> Enum.to_list()
-      [
-        {:status, 200},
-        {:headers, [...]},
-        {:data, "..."},
-        ...
-        :done
-      ]
+      iex> req = Finch.build(:get, "https://httpbin.org/stream/5")
+      iex> ref = Finch.async_request(req, MyFinch)
+      iex> flush()
+      {ref, {:status, 200}}
+      {ref, {:headers, [...]}}
+      {ref, {:data, "..."}}
+      {ref, :done}
 
   ## Options