Improve docs for supervised proceesses

Author: José Valim

lib/elixir/lib/agent.ex

@@ -16,8 +16,8 @@ defmodule Agent do
       defmodule Counter do
         use Agent
 
-        def start_link do
-          Agent.start_link(fn -> 0 end, name: __MODULE__)
+        def start_link(initial_value) do
+          Agent.start_link(fn -> initial_value end, name: __MODULE__)
         end
 
         def value do
@@ -31,7 +31,7 @@ defmodule Agent do
 
   Usage would be:
 
-      Counter.start_link
+      Counter.start_link(0)
 
       Counter.value     #=> 0
       Counter.increment #=> :ok
@@ -71,9 +71,37 @@ defmodule Agent do
   than in the server can lead to race conditions if multiple clients are trying
   to update the same state to different values.
 
-  Finally note that `use Agent` defines a `child_spec/1` function, allowing the
-  defined module to be put under a supervision tree. The generated
-  `child_spec/1` can be customized with the following options:
+  ## How to supervise
+
+  An `Agent` is most commonly started under a supervision tree.
+  When we invoke `use Agent`, it automatically defines a `child_spec/1`
+  function that allows us to start the agent directly under a supervisor.
+  To start an agent under a supervisor with an initial counter of 0,
+  one may do:
+
+      children = [
+        {Counter, 0}
+      ]
+
+      Supervisor.start_link(children, strategy: :one_for_all)
+
+  While one could also simply pass the `Counter` as a child to the supervisor,
+  such as:
+
+      children = [
+        Counter # Same as {Counter, []}
+      ]
+
+      Supervisor.start_link(children, strategy: :one_for_all)
+
+  The definition above wouldn't work for this particular example,
+  as it would attempt to start the counter with an initial value
+  of an empty list. However, this may be a viable option in your
+  own agents.
+
+  `use Agent` also accepts a list of options which configures the
+  child specification and therefore how it runs under a supervisor.
+  The generated `child_spec/1` can be customized with the following options:
 
     * `:id` - the child specification identifier, defaults to the current module
     * `:start` - how to start the child process (defaults to calling `__MODULE__.start_link/1`)

lib/elixir/lib/gen_server.ex

@@ -61,7 +61,9 @@ defmodule GenServer do
 
   Every time you do a `GenServer.call/3`, the client will send a message
   that must be handled by the `c:handle_call/3` callback in the GenServer.
-  A `cast/2` message must be handled by `c:handle_cast/2`.
+  A `cast/2` message must be handled by `c:handle_cast/2`. There are 7 possible
+  callbacks to be implemented when you use a `GenServer`. The only required
+  callback is `init/1`.
 
   ## Client / Server APIs
 
@@ -111,14 +113,33 @@ defmodule GenServer do
   the same module. If the server and/or client implementations are growing
   complex, you may want to have them in different modules.
 
-  ## use GenServer and callbacks
+  ## How to supervise
 
-  There are 7 callbacks to be implemented when you use a `GenServer`.
-  The only required callback is `init/1`.
+  A `GenServer` is most commonly started under a supervision tree.
+  When we invoke `use GenServer`, it automatically defines a `child_spec/1`
+  function that allows us to start the `Stack` directly under a supervisor.
+  To start a default stack of `[:hello]` under a supervisor, one may do:
 
-  `use GenServer` also defines a `child_spec/1` function, allowing the
-  defined module to be put under a supervision tree. The generated
-  `child_spec/1` can be customized with the following options:
+      children = [
+        {Stack, [:hello]}
+      ]
+
+      Supervisor.start_link(children, strategy: :one_for_all)
+
+  Note you can also start it simply as `Stack`, which is the same as
+  `{Stack, []}`:
+
+      children = [
+        Stack # The same as {Stack, []}
+      ]
+
+      Supervisor.start_link(children, strategy: :one_for_all)
+
+  In both cases, `Stack.start_link/1` is alwaus invoked.
+
+  `use GenServer` also accepts a list of options which configures the
+  child specification and therefore how it runs under a supervisor.
+  The generated `child_spec/1` can be customized with the following options:
 
     * `:id` - the child specification identifier, defaults to the current module
     * `:start` - how to start the child process (defaults to calling `__MODULE__.start_link/1`)

lib/elixir/lib/task.ex

@@ -88,11 +88,11 @@ defmodule Task do
       ], strategy: :one_for_one)
 
   Since these tasks are supervised and not directly linked to
-  the caller, they cannot be awaited on. Note that `start_link/1`,
-  unlike `async/1`, returns `{:ok, pid}` (which is the result
-  expected by supervisors).
+  the caller, they cannot be awaited on. `start_link/1`, unlike
+  `async/1`, returns `{:ok, pid}` (which is the result expecte
+  by supervisors).
 
-  Note that `use Task` defines a `child_spec/1` function, allowing the
+  `use Task` defines a `child_spec/1` function, allowing the
   defined module to be put under a supervision tree. The generated
   `child_spec/1` can be customized with the following options: