README.rdoc in transitions-0.1.0 vs README.rdoc in transitions-0.1.1

@@ -1,30 +1,30 @@
-= Travis Build Status 
+=== Travis Build Status 
 
 {<img src="https://secure.travis-ci.org/troessner/transitions.png?branch=master"/>}[http://travis-ci.org/troessner/transitions]
 
-= Synopsis
+=== Synopsis
 
 <tt>transitions</tt> is a ruby state machine implementation.
 
-= Installation
+=== Installation
 
-== Rails
+==== Rails
 
 This goes into your Gemfile:
 
  gem "transitions", :require => ["transitions", "active_model/transitions"]
 
 … and this into your ORM model:
 
  include ActiveModel::Transitions
 
-== Standalone
+==== Standalone
 
  gem install transitions
 
-= Using transitions
+=== Using transitions
 
  class Product
    include ActiveModel::Transitions
  
    state_machine do
@@ -49,20 +49,23 @@
 
  require 'transitions'
 
 whereever you load your dependencies in your application.
 
-= Features
+<b>A word of warning:</b> Use symbols, not strings for declaring the state machine. Using strings is *not* supported as is using whitespace in names (because `transitions` possibly generates methods out of this).
 
-== Events
+=== Features
 
-When you declare an event, say <tt>discontinue</tt>, two methods are declared for
-you: <tt>discontinue</tt> and <tt>discontinue!</tt>. Both events will modify the <tt>state</tt> attribute on successful transition,
-but only the bang(!)-version will call <tt>save!</tt>.
+==== Events
 
-== Automatic scope generation
+When you declare an event, say <tt>discontinue</tt>, three methods are declared for
+you: <tt>discontinue</tt>, <tt>discontinue!</tt> and <tt>can_discontinue?</tt>. The first two events will modify the <tt>state</tt> attribute on successful transition,
+but only the bang(!)-version will call <tt>save!</tt>.  The <tt>can_discontinue?</tt> method will
+not modify state but instead returns a boolean letting you know if a given transition is possible.
 
+==== Automatic scope generation
+
 <tt>transitions</tt> will automatically generate scopes for you if you are using ActiveRecord and tell it to do so via the <tt>auto_scopes</tt> option:
 
 Given a model like this:
 
   class Order < ActiveRecord::Base
@@ -80,20 +83,20 @@
   >> Order.create!
   => #<Order id: 3, state: "pick_line_items", description: nil, created_at: "2011-08-23 15:48:46", updated_at: "2011-08-23 15:48:46">
   >> Order.pick_line_items
   => [#<Order id: 3, state: "pick_line_items", description: nil, created_at: "2011-08-23 15:48:46", updated_at: "2011-08-23 15:48:46">]
 
-== Using <tt>on_transition</tt>
+==== Using <tt>on_transition</tt>
 
 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 => :discontinued, :from => [:available, :out_of_stock], :on_transition => [:do_discontinue, :notify_clerk]
   end
 
-== Using <tt>success</tt>
+==== Using <tt>success</tt>
 
 In case you need to trigger a method call after a successful transition you can use <tt>success</tt>:
 
   event :discontinue, :success => :notfiy_admin do
     transitions :to => :discontinued, :from => [:available, :out_of_stock]
@@ -104,11 +107,11 @@
 
   event :discontinue, :success => lambda { |order) AdminNotifier.notify_about_discontinued_order(order) } do
     transitions :to => :discontinued, :from => [:available, :out_of_stock]
   end
 
-== Timestamps
+==== Timestamps
 
 If you'd like to note the time of a state change, Transitions comes with timestamps free!
 To activate them, simply pass the :timestamp option to the event definition with a value of either true or
 the name of the timestamp column.
 *NOTE - This should be either true, a String or a Symbol*
@@ -122,11 +125,11 @@
   # This will look for an attribute named repaired_on to update upon save
   event :rebuild, :timestamp => :repaired_on do
     transitions :from => :exploded, :to => :rebuilt
   end
 
-== `event_fired` and `event_failed`
+====  Using <tt>event_fired</tt> and <tt>event_failed</tt>
 
 In case you define `event_fired` and / or `event_failed`, `transitions` will use those callbacks correspondingly.
 You can use those callbacks like this:
 
   def event_fired(current_state, new_state, event)
@@ -135,23 +138,26 @@
 
   def event_failed(event)
     MyLogger.warn "Event failed #{event.inspect}"
   end
 
-== Listing all the available states
+==== Listing all the available states
 
 You can easily get a listing of all available states:
 
   Order.available_states # Uses the <tt>default</tt> state machine
   # => [:pick_line_items, :picking_line_items]
 
-In case you have multiple state machines you can also pass the state machine name:
+==== Explicitly setting the initial state with the <tt>initial</tt> option
 
-  Order.available_states(:your_machine)
+  state_machine :initial => :closed do
+    state :open
+    state :closed
+  end
 
-= Documentation, Guides & Examples
+=== Documentation, Guides & Examples
 
 - {Online API Documentation}[http://rdoc.info/github/troessner/transitions/master/Transitions]
 
-= Copyright
+=== Copyright
 
 Copyright (c) 2010 Jakub Kuźma, Timo Rößner. See LICENSE for details.