Merge pull request #1830 from jwarwick/behaviour_docs

Doc updates for Application.Behaviour and Behaviour

Author: José Valim

lib/elixir/lib/application/behaviour.ex

@@ -1,40 +1,40 @@
 defmodule Application.Behaviour do
   @moduledoc """
-  This module is a convenience to define application module callbacks.
+  Default callbacks for applications.
 
   In Erlang/OTP, an application is a component that can be started
-  and stopped as a unit, and which can be re-used in other systems
-  as well.
+  and stopped as a unit, and which can be reused in other systems.
 
-  The first step to achieve this is to define an application specification.
+  The first step in creating an application is to define an application specification.
   For example, if your application is named `:my_app`, an app specification
   should exist at `ebin/my_app.app`. This file is usually defined by
   build tools like Mix.
 
-  Then, with the app specification in hands, we must also define an
-  application module callback that controls how to start and stop
-  such applications. This module is about defining such callbacks.
+  With the app specification in hand, we must define
+  application module callbacks that control how to start and stop
+  instances of the application. This module is about defining such callbacks.
 
-  There are two callbacks required to be implemented:
+  There are two callbacks which must be implemented:
 
-  1. `start(type, args)` - It must return `{ :ok, pid }` or
+  1. `start(type, args)` - must return `{ :ok, pid }` or
      `{ :ok, pid, state }`, where `pid` is the process identifier
-     of the supervisor tree root;
+     of the supervisor tree root and `state` is application defined 
+     state information;
 
-  2. `stop(state)` receives the state returned by `start` and should
-     do any necessary cleaning up. Notice that shutting down the supervisor
+  2. `stop(state)` - receives the `state` returned by `start` and should
+     do any necessary clean up. Notice that shutting down the supervisor
      is automatically handled by the VM;
 
-  When using this module, it simply tags the module behaviour as
-  `:application` and defines a default `stop/1` callback. The `start/2`
-  still needs to be defined by the user.
+  When using this module, it tags the module behaviour as
+  `:application` and provides a default `stop/1` callback. The `start/2` callback
+  still needs to be implemented by the user.
 
   You can learn more about the `:application` module, the application
-  specification and the application module callbacks below:
+  specification and the application module callbacks from these sources:
 
-  http://www.erlang.org/doc/man/application.html
-  http://www.erlang.org/doc/design_principles/applications.html
-  http://learnyousomeerlang.com/building-otp-applications
+  * http://www.erlang.org/doc/man/application.html
+  * http://www.erlang.org/doc/design_principles/applications.html
+  * http://learnyousomeerlang.com/building-otp-applications
 
   ## Example
 
@@ -102,4 +102,4 @@ defmodule Application.Behaviour do
       defoverridable [stop: 1]
     end
   end
-end
+end

lib/elixir/lib/behaviour.ex

@@ -1,12 +1,12 @@
 defmodule Behaviour do
   @moduledoc """
-  A convenience module for defining behaviours.
+  Utilities for defining behaviour intefaces.
+
   Behaviours can be referenced by other modules
-  in order to ensure they implement the proper
-  callbacks.
+  to ensure they implement required callbacks.
 
   For example, you can specify the `URI.Parser`
-  behaviour as follow:
+  behaviour as follows:
 
       defmodule URI.Parser do
         use Behaviour
@@ -18,32 +18,33 @@ defmodule Behaviour do
         defcallback default_port() :: integer
       end
 
-  And then a specific module may use it as:
+  And then a module may use it as:
 
       defmodule URI.HTTP do
         @behaviour URI.Parser
         def default_port(), do: 80
         def parse(info), do: info
       end
 
-  In case the behaviour changes or URI.HTTP does
+  If the behaviour changes or `URI.HTTP` does
   not implement one of the callbacks, a warning
   will be raised.
 
   ## Implementation
 
-  Behaviours since Erlang R15 must be defined via
+  Since Erlang R15, behaviours must be defined via
   `@callback` attributes. `defcallback` is a simple
   mechanism that defines the `@callback` attribute
-  according to the type specification and also allows
-  docs and defines a custom function signature.
+  according to the given type specification. `defcallback` allows
+  documentsion to be created for the callback and defines 
+  a custom function signature.
 
   The callbacks and their documentation can be retrieved
   via the `__behaviour__` callback function.
   """
 
   @doc """
-  Defines a callback according to the given type specification.
+  Define a function callback according to the given type specification.
   """
   defmacro defcallback({ :::, _, [fun, return] }) do
     do_defcallback(fun, return, __CALLER__)
@@ -54,7 +55,7 @@ defmodule Behaviour do
   end
 
   @doc """
-  Defines a macro callback according to the given type specification.
+  Define a macro callback according to the given type specification.
   """
   defmacro defmacrocallback({ :::, _, [fun, return] }) do
     do_defmacrocallback(fun, return, __CALLER__)