Merge pull request #5 from joaomdmoura/fixing-docs

Updating README and wrong docs

Author: joaomdmoura

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## WIP Version
 
+## 0.4.1
+- Updating wrong docs and README - [Pull Request](https://github.com/joaomdmoura/machinery/pull/3)
+
 ## 0.4.0
 - New, more functional DSL, not relying on Macros so much - [Pull Request](https://github.com/joaomdmoura/machinery/pull/1)
 - Adding support for before and after callbacks - [Pull Request](https://github.com/joaomdmoura/machinery/pull/2)

README.md

@@ -28,27 +28,28 @@ dependencies in `mix.exs`:
 ```elixir
 def deps do
   [
-    {:machinery, "~> 0.4.0"}
+    {:machinery, "~> 0.4.1"}
   ]
 end
 ```
 
 ## Declaring States
 
-Declare the states you need pasing it as an argment when importing `Machinery`
-on the module that will control your states transitions.
+Declare the states as an argment when importing `Machinery` on the module that
+will control your states transitions.
 
 Machinery expects a `Keyword` as argument with two keys `states` and `transitions`.
 
 - `states`: A List of Atoms representing each state.
-- `transitions`: A List of Maps, including two keys `from` and `to`, `to` might be an Atom or a List of Atoms.
+- `transitions`: A Map for each state and it allowed next state(s).
 
 ### Example
 
 ```elixir
 defmodule YourProject.UserStateMachine do
   use Machinery,
-    # The first state declared will be considered the intial state
+    # The first state declared will be considered
+    # the intial state
     states: [:created, :partial, :complete],
     transitions: %{
       created: [:partial, :complete],
@@ -59,13 +60,15 @@ end
 
 ## Changing States
 
-To transit a struct into another state, you just need to call `Machinery.transition_to/2`
+To transit a struct into another state, you just need to call `Machinery.transition_to/2`.
 
 ### `Machinery.transition_to/2`
 It takes two arguments:
 
-- `struct`: The struct you want to transit to another state
-- `next_event`: An atom representing the next state you want the struct to transition to
+- `struct`: The `struct` you want to transit to another state.
+- `next_event`: An `atom` of the next state you want the struct to transition to.
+
+**Guard functions, before and after callbacks will be checked automatically.**
 
 ```elixir
 Machinery.transition_to(your_struct, :next_state)
@@ -79,26 +82,27 @@ user = Accounts.get_user!(1)
 UserStateMachine.transition_to(user, :partial)
 ```
 
-Guard functions, before and after callbacks will be checked automatically.
-
 ## Guard functions
 Create guard conditions by adding signatures of the `guard_transition/2`
 function, pattern matching the desired state you want to guard.
 
+```elixir
+def guard_transition(struct, :state), do: true
+```
+
 Guard conditions should return a boolean:
   - `true`: Guard clause will allow the transition.
   - `false`: Transition won't be allowed.
 
+### Example:
+
 ```elixir
 defmodule YourProject.UserStateMachine do
   use Machinery,
-    # The first state declared will be considered the intial state
-    states: [:created, :partial, :complete],
-    transitions: %{
-      created: [:partial, :complete],
-      partial: :completed
-    }
+    states: [:created, :complete],
+    transitions: %{created: :complete}
 
+  # Guard the transition to the :complete state.
   def guard_transition(struct, :complete) do
    Map.get(struct, :missing_fields) == false
   end
@@ -108,27 +112,37 @@ end
 ## Before and After callbacks
 
 You can also use before and after callbacks to handle desired side effects and
-reactions to a specific state transition, the implementation is pretty similar to
-guard functions, you can just declare `before_transition/2` and ``after_transition/2`.
-Before and After callbacks should return the struct being manipulated.
+reactions to a specific state transition.
+
+You can just declare `before_transition/2` and `  after_transition/2`,
+pattern matching the desired state you want to.
+
+**Make sure Before and After callbacks should return the struct.**
+
+```elixir
+# callbacks should always return the struct.
+def before_transition(struct, :state), do: struct
+def after_transition(struct, :state), do: struct
+```
+
+### Example:
 
 ```elixir
 defmodule YourProject.UserStateMachine do
   use Machinery,
-    # The first state declared will be considered the intial state
     states: [:created, :partial, :complete],
     transitions: %{
       created: [:partial, :complete],
       partial: :completed
     }
 
-   def before_transition(struct, :partial) do
-      # ... overall desired side effect
+    def before_transition(struct, :partial) do
+      # ... overall desired side effects
       struct
     end
 
     def after_transition(struct, :completed) do
-      # ... overall desired side effect
+      # ... overall desired side effects
       struct
     end
 end

lib/machinery.ex

@@ -1,25 +1,25 @@
 defmodule Machinery do
   @moduledoc """
   Main Machinery module.
-  It keeps the bunk of the Machinery logics, it's the module that
-  will be imported with `use` on the module that the state machine will
-  be implemented.
+  It keeps the bunk of the Machinery logics, it's the module that will be
+  imported with `use` on the module that the state machine will be implemented.
+  The first state declared will be considered the intial state
 
   ## Parameters
 
     - `opts`: A Keyword including `states` and `transitions`.
       - `states`: A List of Atoms representing each state.
-      - `transitions`: A List of Maps, including two keys `from` and `to`, `to` might be an Atom or a List of Atoms.
+      - `transitions`: A Map for each state and it allowed next state(s).
 
   ## Example
     ```
     defmodule Project.User do
       use Machinery,
         states: [:created, :partial, :complete],
-        transitions: [
-          %{from: :created, to: [:partial, :complete]},
-          %{from: :partal, to: :complete}
-        ]
+        transitions: %{
+          created: [:partial, :complete],
+          partial: :completed
+        }
     end
     ```
   """
@@ -54,9 +54,9 @@ defmodule Machinery do
   end
 
   @doc """
-  Triggers the transition of a struct to a new state if it passes the
+  Triggers the transition of a struct to a new state, if it passes any
   existing guard clause, also runs any before or after callbacks.
-  It returns a tuple with `{:ok, state}`, or `{:error, "cause"}`.
+  It returns a tuple with `{:ok, struct}`, or `{:error, "reason"}`.
 
   ## Parameters
 

mix.exs

@@ -4,7 +4,7 @@ defmodule Machinery.Mixfile do
   def project do
     [
       app: :machinery,
-      version: "0.4.0",
+      version: "0.4.1",
       elixir: "~> 1.5",
       start_permanent: Mix.env == :prod,
       deps: deps(),