README.rdoc in transitions-0.0.9 vs README.rdoc in transitions-0.0.10

@@ -1,42 +1,89 @@
-= transitions
+= What is transitions?
 
-The gem is based on Rick Olson's code of ActiveModel::StateMachine,
-axed from ActiveModel in {this
-commit}[http://github.com/rails/rails/commit/db49c706b62e7ea2ab93f05399dbfddf5087ee0c].
+transitions is a ruby state machine implementation based on Rick Olson’s
+ActiveModel::StateMachine. It was extracted from ActiveModel and turned
+into a gem when it got the axe in commit {db49c706b}[http://github.com/rails/rails/commit/db49c706b62e7ea2ab93f05399dbfddf5087ee0c].
 
-== Installation
+I really encourage you to try {state_machine}[https://github.com/pluginaweek/state_machine] before using this gem. Currently I have no time to maintain the gem, if you want to add some new features - contact with me.
 
-If you're using Rails + ActiveRecord + Bundler
+== Quick Example
 
-  # in your Gemfile
-  gem "transitions", :require => ["transitions", "active_record/transitions"]
+ require 'transitions'
+ 
+ class Product
+   include Transitions
+ 
+   state_machine do
+     state :available # first one is initial state
+     state :out_of_stock, :exit => :exit_out_of_stock
+     state :discontinued, :enter => lambda { |product| product.cancel_orders }
+   
+     event :discontinued do
+       transitions :to => :discontinued, :from => [:available, :out_of_stock], :on_transition => :do_discontinue
+     end
+     event :out_of_stock do
+       transitions :to => :out_of_stock, :from => [:available, :discontinued]
+     end
+     event :available do
+       transitions :to => :available, :from => [:out_of_stock], :guard => lambda { |product| product.in_stock > 0 }
+     end
+   end
+ end
 
-  # in your AR models that will use the state machine
-  include ::Transitions
-  include ActiveRecord::Transitions
+== Using on_transition
 
-  state_machine do
-    state :available # first one is initial state
-    state :out_of_stock
-    state :discontinue
+Each event definition takes an optional "on_transition" argument, which allows you to execute methods on transition.
+You can pass in a Symbol, a String, a Proc or an Array containing method names as Symbol or String like this:
 
-    event :discontinue do
-      transitions :to => :discontinue, :from => [:available, :out_of_stock], :on_transition => :do_discontinue
-    end
-    event :out_of_stock do
-      transitions :to => :out_of_stock, :from => [:available, :discontinue]
-    end
-    event :available do
-      transitions :to => :available, :from => [:out_of_stock], :on_transition => :send_alerts
-    end
+  event :discontinue do
+    transitions :to => :discontinued, :from => [:available, :out_of_stock], :on_transition => [:do_discontinue, :notify_clerk]
   end
 
-== Usage
+== Using with Rails
 
-Krzysiek Heród (aka {Netizer}[http://github.com/netizer]) wrote a nice {blog
-post}[http://dev.netizer.pl/transitions-state-machine-for-rails-3.html]
-about using Transitions in ActiveRecord.
+This goes into your Gemfile:
+
+ gem "transitions", :require => ["transitions", "active_record/transitions"]
+
+… and this into your AR model:
+
+ include ActiveRecord::Transitions
+
+=== A note about persistence
+The property used to persist the models’ state is named <tt>state</tt> (really!),
+which should be a string column wide enough to fit your longest state name.
+It should also be mentioned that <tt>#save!</tt> is called after every successful event.
+
+== Event execution flow
+
+On an event, with our quick example product going from <tt>:available</tt> to
+<tt>:discontinued</tt> it looks like this:
+
+1. <tt>baby_ninja.discontinue!(:reason => :pirates)</tt>
+2. call <tt>:exit</tt> handler of <tt>:available</tt> state
+3. call <tt>:guard</tt> of <tt>:available to :discontinue</tt> transition within <tt>#discontinue</tt> event
+4. call <tt>#event_failed(:event)</tt> and abort unless <tt>3.</tt> returned <tt>true</tt>
+5. call <tt>:on_transition(:reason => :pirates)</tt> of <tt>:available to :discontinue</tt> transition within <tt>#discontinue</tt> event
+6. call <tt>:enter</tt> handler of <tt>:discontinue</tt>
+7. call <tt>#event_fired(:available, :discontinue)</tt>
+8. call <tt>#write_state(machine, :discontinue)</tt>
+9. call <tt>#write_state_without_persistence(machine, :discontinue)</tt>
+10. call <tt>baby_ninja#:success</tt> handler method of <tt>#discontinue</tt> event
+
+=== A note about events
+
+When you declare an event <tt>discontinue</tt>, two methods are declared for
+you: <tt>discontinue</tt> and <tt>discontinue!</tt>. Both events will call
+<tt>write_state_without_persistence</tt> on successful transition, but only the
+bang(!)-version will call <tt>write_state</tt>.
+
+== Documentation, Guides & Examples
+
+- {Online API Documentation}[http://rdoc.info/github/qoobaa/transitions/master/Transitions]
+- Krzysiek Heród (aka {Netizer}[http://github.com/netizer]) wrote a nice
+  {blog post}[http://dev.netizer.pl/transitions-state-machine-for-rails-3.html]
+  about using Transitions in ActiveRecord.
 
 == Copyright
 
 Copyright (c) 2010 Jakub Kuźma. See LICENSE for details.