lib/state_machine.rb in state_machine-0.9.2 vs lib/state_machine.rb in state_machine-0.9.3

@@ -88,20 +88,53 @@
     #     state_machine :status, :initial => lambda {|vehicle| vehicle.speed == 0 ? :parked : :idling} do
     #       ...
     #     end
     #   end
     # 
+    # == Class Methods
+    # 
+    # The following class methods will be automatically generated by the
+    # state machine based on the *name* of the machine.  Any existing methods
+    # will not be overwritten.
+    # * <tt>human_state_name(state)</tt> - Gets the humanized value for the
+    #   given state.  This may be generated by internationalization libraries if
+    #   supported by the integration.
+    # * <tt>human_state_event_name(event)</tt> - Gets the humanized value for
+    #   the given event.  This may be generated by internationalization
+    #   libraries if supported by the integration.
+    # 
+    # For example,
+    # 
+    #   class Vehicle
+    #     state_machine :state, :initial => :parked do
+    #       event :ignite do
+    #         transition :parked => :idling
+    #       end
+    #       
+    #       event :shift_up do
+    #         transition :idling => :first_gear
+    #       end
+    #     end
+    #   end
+    #   
+    #   Vehicle.human_state_name(:parked)         # => "parked"
+    #   Vehicle.human_state_name(:first_gear)     # => "first gear"
+    #   Vehicle.human_state_event_name(:park)     # => "park"
+    #   Vehicle.human_state_event_name(:shift_up) # => "shift up"
+    # 
     # == Instance Methods
     # 
     # The following instance methods will be automatically generated by the
     # state machine based on the *name* of the machine.  Any existing methods
     # will not be overwritten.
     # * <tt>state</tt> - Gets the current value for the attribute
     # * <tt>state=(value)</tt> - Sets the current value for the attribute
     # * <tt>state?(name)</tt> - Checks the given state name against the current
     #   state.  If the name is not a known state, then an ArgumentError is raised.
     # * <tt>state_name</tt> - Gets the name of the state for the current value
+    # * <tt>human_state_name</tt> - Gets the human-readable name of the state
+    #   for the current value
     # * <tt>state_events</tt> - Gets the list of events that can be fired on
     #   the current object's state (uses the *unqualified* event names)
     # * <tt>state_transitions(requirements = {})</tt> - Gets the list of possible
     #   transitions that can be made on the current object's state.  Additional
     #   requirements, such as the :from / :to state and :on event can be specified
@@ -123,9 +156,10 @@
     #   end
     #   
     #   vehicle = Vehicle.new
     #   vehicle.state                     # => "parked"
     #   vehicle.state_name                # => :parked
+    #   vehicle.human_state_name          # => "parked"
     #   vehicle.state?(:parked)           # => true
     #   
     #   # Changing state
     #   vehicle.state = 'idling'
     #   vehicle.state                     # => "idling"