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