Merge pull request #2322 from alco/agent-doc

Proof-read Agent docs

Author: José Valim

lib/elixir/lib/agent.ex

@@ -31,7 +31,7 @@ defmodule Agent do
         @doc "Marks a task as executed"
         def put_task(task, project) do
           item = {task, project}
-          Agent.update(__MODULE__, &Set.put(item, &1))
+          Agent.update(__MODULE__, &Set.put(&1, item))
         end
       end
 
@@ -54,34 +54,35 @@ defmodule Agent do
         Agent.get(agent, &(&1)) |> do_something_expensive()
       end
 
-  The first one blocks the agent while the second one moves copies
-  all the state to the client and execute the operation in the client.
+  The first one blocks the agent while the second one copies
+  all the state to the client and executes the operation in the client.
   The trade-off here is exactly if the data is small enough to be
   sent to the client cheaply or large enough to require processing on
   the server (or at least some initial processing).
 
-  ## Name registering
+  ## Name registration
 
-  An Agent is bound to the same name registering rules as a `GenServer`.
+  An Agent is bound to the same name registration rules as GenServers.
   Read more about it in the `GenServer` docs.
 
   ## A word on distributed agents
 
-  It is important to consider the limitation of distributed agents. Agents
+  It is important to consider the limitations of distributed agents. Agents
   work by sending anonymous functions in between the caller and the agent.
   In a distributed setup with multiple nodes, agents only work if the caller
   (client) and the agent have the same version of a given module.
 
   This setup may exhibit issues when doing "rolling upgrades". By rolling
-  upgrades we mean that you desire to deploy a new version your software
-  by *shutting down* some of your nodes and replace them by nodes running
-  a new version of the software. In this setup, part of your environment
-  will have one version of a given module and other part another version
-  of the same module, which may lead agents to crash. That said, if you
-  plan to run on distributed environments, agents should likely be avoided.
-
-  Note however agents work fine if you want to perform hot code swap, as
-  hot code swapping keeps both the old and new versions of a given module.
+  upgrades we mean the following situation: you wish to deploy a new version of
+  your software by *shutting down* some of your nodes and replacing them by
+  nodes running a new version of the software. In this setup, part of your
+  environment will have one version of a given module and the other part
+  another version (the newer one) of the same module; this may cause agents to
+  crash. That said, if you plan to run in distributed environments, agents
+  should likely be avoided.
+
+  Note, however, that agents work fine if you want to perform hot code
+  swapping, as it keeps both the old and new versions of a given module.
   We detail how to do hot code swapping with agents in the next section.
 
   ## Hot code swapping
@@ -94,7 +95,7 @@ defmodule Agent do
 
       {:update, :sample, {:advanced, {Enum, :into, [%{}]}}}
 
-  The agent state will be added as first argument of the arguments list.
+  The agent's state will be added to the given list as the first argument.
   """
 
   @typedoc "Return values of `start*` functions"
@@ -115,30 +116,30 @@ defmodule Agent do
   This is often used to start the agent as part of a supervision tree.
 
   Once the agent is spawned, the given function is invoked and its return
-  value is used as the agent state. Note this function does not return
+  value is used as the agent state. Note that `start_link` does not return
   until the given function has returned.
 
   ## Options
 
-  The `:name` option is used for name registered as described in the module
-  documentation. If the option `:timeout` option is present, the agent is
-  allowed to spend the given milliseconds initializing or it will be terminated
-  and the start function will return `{:error, :timeout}`.
+  The `:name` option is used for registration as described in the module
+  documentation. If the `:timeout` option is present, the agent is allowed to
+  spend at most the given amount of milliseconds on initialization or it will
+  be terminated and the start function will return `{:error, :timeout}`.
 
-  If the option `:debug` is present, the corresponding function in the
+  If the `:debug` option is present, the corresponding function in the
   [`:sys` module](http://www.erlang.org/doc/man/sys.html) will be invoked.
 
-  If the option `:spawn_opt` is present, the given options will be passed
+  If the `:spawn_opt` option is present, its value will be passed as options
   to the underlying process as in `Process.spawn/3`.
 
   ## Return values
 
-  If the server is successfully created and initialized the function returns
+  If the server is successfully created and initialized, the function returns
   `{:ok, pid}`, where pid is the pid of the server. If there already exists
-  an agent with the specified name the function returns
+  an agent with the specified name, the function returns
   `{:error, {:already_started, pid}}` with the pid of that process.
 
-  If the given function callback fails with reason, the function returns
+  If the given function callback fails with `reason`, the function returns
   `{:error, reason}`.
   """
   @spec start_link((() -> term), GenServer.options) :: on_start
@@ -175,7 +176,7 @@ defmodule Agent do
 
   The function `fun` is sent to the `agent` which invokes the function
   passing the agent state. The function must return a tuple with two
-  elements, the first being the value to returned (i.e. the get value)
+  elements, the first being the value to return (i.e. the get value)
   and the second one is the new state.
 
   A timeout can also be specified (it has a default value of 5000).
@@ -192,7 +193,7 @@ defmodule Agent do
   passing the agent state. The function must return the new state.
 
   A timeout can also be specified (it has a default value of 5000).
-  This function always return `:ok`.
+  This function always returns `:ok`.
   """
   @spec update(agent, (state -> state)) :: :ok
   def update(agent, fun, timeout \\ 5000) when is_function(fun, 1) do
@@ -205,8 +206,8 @@ defmodule Agent do
   The function `fun` is sent to the `agent` which invokes the function
   passing the agent state. The function must return the new state.
 
-  Note this function returns `:ok` immediately, ignoring if the
-  destination node or agent does not exist.
+  Note that `cast` returns `:ok` immediately, regardless of whether the
+  destination node or agent exists.
   """
   @spec cast(agent, (state -> state)) :: :ok
   def cast(agent, fun) when is_function(fun, 1) do
@@ -216,7 +217,7 @@ defmodule Agent do
   @doc """
   Stops the agent.
 
-  Returns `:ok` if the agent is stopped in the given `timeout`.
+  Returns `:ok` if the agent is stopped within the given `timeout`.
   """
   @spec stop(agent, timeout) :: :ok
   def stop(agent, timeout \\ 5000) do