Update capture_io.ex

Author: josevalim

Diff for: lib/ex_unit/lib/ex_unit/capture_io.ex

@@ -29,15 +29,15 @@ defmodule ExUnit.CaptureIO do
 
   Returns the binary which is the captured output.
 
-  By default, `capture_io` replaces the `group_leader` (`:stdio`)
-  for the current process. Capturing the group leader is done per
-  process and therefore can be done concurrently.
+  By default, `capture_io` replaces the `Process.group_leader/0` of the current
+  process, which is the process used by default for all IO operations. Capturing
+  the group leader of the current process is safe to run concurrently, under
+  `async: true` tests. You may also explicitly capture the group leader of
+  another process, however that is not safe to do concurrently.
 
-  However, the capturing of any other named device, such as `:stderr`,
-  happens globally and persists until the function has ended. While this means
-  it is safe to run your tests with `async: true` in many cases, captured output
-  may include output from a different test and care must be taken when using
-  `capture_io` with a named process asynchronously.
+  You may also capture any other named IO device, such as `:stderr`. This is
+  also safe to run concurrently but, if several tests are writting to the same
+  device at once, captured output may include output from a different test.
 
   A developer can set a string as an input. The default input is an empty
   string. If capturing a named device asynchronously, an input can only be given
@@ -51,15 +51,28 @@ defmodule ExUnit.CaptureIO do
 
   ## IO devices
 
-  You may capture the IO from any registered IO device. The device name given
-  must be an atom representing the name of a registered process. In addition,
-  Elixir provides two shortcuts:
+  You may capture the IO of the group leader of any process, by passing a `pid`
+  as argument, or from any registered IO device given as an `atom`. Here are
+  some example values:
 
-    * `:stdio` - a shortcut for `:standard_io`, which maps to
-      the current `Process.group_leader/0` in Erlang
+    * `:stdio`, `:standard_io` - a shortcut for capturing the group leader
+      of the current process. It is equivalent to passing `self()` as the
+      first argument. This is safe to run concurrently and captures only
+      the of the current process or any child process spawned inside the
+      given function
 
-    * `:stderr` - a shortcut for the named process `:standard_error`
-      provided in Erlang
+    * `:stderr`, `:standard_error` - captures all IO to standard error
+      (represented internally by an Erlang process named `:standard_error`).
+      This is safe to run concurrently but it will capture the output
+      of any other test writing to the same named device
+
+    * any other atom - captures all IO to the given device given by the
+      atom. This is safe to run concurrently but it will capture the output
+      of any other test writing to the same named device
+
+    * any other pid (since v1.17.0) - captures all IO to the group leader
+      of the given process. This option is not safe to run concurrently
+      if the pid is not `self()`. Tests using this value must set `async: true`
 
   ## Options
 
@@ -72,9 +85,6 @@ defmodule ExUnit.CaptureIO do
     * `:encoding` (since v1.10.0) - encoding of the IO device. Allowed
       values are `:unicode` (default) and `:latin1`.
 
-    * `:pid` (since v1.17.0) - a process identifier. This option can be
-      used to capture IO from an already-started process.
-
   ## Examples
 
   To capture the standard io:
@@ -94,10 +104,10 @@ defmodule ExUnit.CaptureIO do
       ...> end) == "this is input"
       true
 
-  Note it is fine to use `==` with standard IO, because the content is captured
-  per test process. However, `:stderr` is shared across all tests, so you will
-  want to use `=~` instead of `==` for assertions on `:stderr` if your tests
-  are async:
+  Note it is fine to use `==` with `:stdio` (the default IO device), because
+  the content is captured per test process. However, `:stderr` is shared
+  across all tests, so you will want to use `=~` instead of `==` for assertions
+  on `:stderr` if your tests are async:
 
       iex> capture_io(:stderr, fn -> IO.write(:stderr, "john") end) =~ "john"
       true
@@ -113,6 +123,14 @@ defmodule ExUnit.CaptureIO do
   Otherwise, if the standard error of any other test is captured, the test will
   fail.
 
+  To capture the IO from another process, you can pass a `pid`:
+
+      capture_io(GenServer.whereis(MyServer), fn ->
+        GenServer.call(MyServer, :do_something)
+      end)
+
+  Tests that directly capture a PID cannot run concurrently.
+
   ## Returning values
 
   As seen in the examples above, `capture_io` returns the captured output.