 defmodule GenFSM.Behaviour do
   @moduledoc """
-  This module is a convenience to define GenFsm callbacks in Elixir.
-
-  A FSM (finite state machine) is responsible for reacting to events received
-  and a GenFSM is an OTP behaviour that encapsulates common FSM
+  This module is a convenience for defining GenFSM callbacks in Elixir.
+
+  A finite state machine (FSM) is responsible for reacting to events received;
+  GenFSM is an OTP behaviour that encapsulates common FSM
   functionalities.
 
   ## Example
 
-  Bellow follows an example of a GenFSM that runs a very simple minded
+  Below is an example of a GenFSM that runs a very simple minded
   coffee vending machine (CVM). The CVM treats all coins the same. If
-  you press the request button then the CVM will brew coffee if you
-  have paid enough coins, if not it will wait until you have inserted
-  enough coins and then it will instantly brew the coffee since you
-  had already pressed the request button! As we told you - a very
+  you press the request button then the CVM will brew coffee, if you
+  have paid enough coins; if not, it will wait until you have inserted
+  enough coins and then it will instantly brew the coffee, since you
+  had already pressed the request button. As we told you - a very
   simple minded CVM! And greedy too. If you insert more coins than you
-  need it will gladly eat them all until you press the request button.
-
-  We will leave it to the service minded reader to improve the way CVM
+  need it will gladly eat them until you press the request button.
+
+  We will leave it to the service-minded reader to improve the way the CVM
   works - we hereby declare a full disclaimer for any lawsuits that the
-  behaviour of CVM in its original state might encur.
+  behaviour of the CVM in its original state might encur.
 
 
       defmodule MyFsm do
         use GenFSM.Behaviour
 
         # keeping track of what is going on inside the CVM.
+        # 3 coins is the target price for a cup of coffee
         defrecord StateData, coins: 0, price: 3
 
         # API functions

      { :stop, reason, new_state_date }

  There are 6 callbacks required to be implemented in a GenFsm plus 1
  or 2 for each state. The `GenFsm.Behaviour` module defines
  `handle_sync_event`, `handle_info`, `terminate` and `code_change`
  for you. The list of callbacks are:

  * `init(args)` - invoked when the FSM is started;
  * `handle_sync_event(event, from, state_name, state_data)`
    - invoked to handle sync_send_all_state_event messages;
  * `handle_event(event, state_name, state_data)`
    - invoked to handle send_all_state_event messages;
  * `handle_info(msg, state_name, state_data)`
    - handle all other messages which are normally received by processes;
  * `terminate(reason, state_name, state_data)`
     - called when the FSM is about to terminate, useful for cleaning up;
  * `code_change(old_vsn, state, extra)`
    - called when the application code is being upgraded live (hot code swap);

  Differently from `GenServer` and `GenEvent`, the callback `init/1` is not
  implemented by default, as it requires the next state to be returned.

  For each state you need to define either or both of these:

  * `state_name(event, state_data)`
    - invoked to handle `send_event` messages;
  * `state_name(event, from, state_data)`
    - invoked to handle `sync_send_event` messages;

  If you send asynchronous events you only need to implement the
  `state_name/2` variant and vice-versa for synchronous events and

  `:gen_fsm` module. For more information, please refer to the
  following:

  * http://www.erlang.org/doc/man/gen_fsm.html
  * http://www.erlang.org/doc/design_principles/fsm.html
  * http://learnyousomeerlang.com/finite-state-machines
  """

  @doc false
