Document side-effects on stream APIs

Author: José Valim

lib/elixir/lib/file.ex

@@ -973,7 +973,7 @@ defmodule File do
   of bytes given by `line_or_bytes`.
 
   The returned stream will fail for the same reasons as `File.open!`.
-  Note that the file is opened only when streaming begins.
+  Note that the file is opened only and every time streaming begins.
   """
   def stream!(file, mode // [], line_or_bytes // :line) do
     fn(acc, fun) ->
@@ -992,7 +992,7 @@ defmodule File do
   of bytes given by `line_or_bytes`.
 
   The returned stream will fail for the same reasons as `File.open!`.
-  Note that the file is opened only when streaming begins.
+  Note that the file is opened only and every time streaming begins.
   """
   def binstream!(file, mode // [], line_or_bytes // :line) do
     fn(fun, acc) ->

lib/elixir/lib/io.ex

@@ -224,12 +224,15 @@ defmodule IO do
 
   @doc """
   Converts the io device into a Stream. The device is
-  iterated line by line if :line is given or by a given
+  iterated line by line if `:line` is given or by a given
   number of codepoints.
 
-  This reads the io as utf-8. Check out
+  This reads the IO as utf-8. Check out
   `IO.binstream/2` to handle the IO as a raw binary.
 
+  Note that an IO stream has side effects and every time
+  you go over the stream you may get different results.
+
   ## Examples
 
   Here is an example on how we mimic an echo server
@@ -245,9 +248,11 @@ defmodule IO do
 
   @doc """
   Converts the io device into a Stream. The device is
-  iterated line by line.
+  iterated line by line or by a number of bytes. This
+  reads the IO as a raw binary.
 
-  This reads the io as a raw binary.
+  Note that an IO stream has side effects and every time
+  you go over the stream you may get different results.
   """
   @spec binstream(device, :line | pos_integer) :: Enumerable.t
   def binstream(device, line_or_bytes) do