state_gate 1.2.3 → 1.3.0

data/lib/state_gate/builder/state_methods.rb

@@ -8,37 +8,37 @@ module StateGate
     # Multiple private methods enabling StateGate::Builder to generate
     # state functionality.
     #
-    # * query the class for all state:
-    #     Klass.statuses  # => [:pending, :active, :archived]
+    # - query the class for all state:
+    #     Klass.statuses  #=> [:pending, :active, :archived]
     #
-    # * query the class for the human names of all state:
-    #     Klass.human_statuses  # => ['Pending Activation', 'Active', 'Archived']
+    # - query the class for the human names of all state:
+    #     Klass.human_statuses  #=> ['Pending Activation', 'Active', 'Archived']
     #
-    # * query the class for an Array of human names/state names for use in a select form:
+    # - query the class for an Array of human names/state names for use in a select form:
     #     Klass.statuses_for_select
-    #     # => [['Pending Activation', 'pending'],["Active', 'active'], ['Archived','archived']]
+    #     #=> [['Pending Activation', 'pending'],["Active', 'active'], ['Archived','archived']]
     #
-    # * list all attribute states:
-    #     .status_states  # => [:pending, :active, :archived]
+    # - list all attribute states:
+    #     .status_states  #=> [:pending, :active, :archived]
     #
-    # * list all human names for the attribute states:
-    #     .status_human_names  # => ['Pending Activation', 'Active', 'Archived']
+    # - list all human names for the attribute states:
+    #     .status_human_names  #=> ['Pending Activation', 'Active', 'Archived']
     #
-    # * list the human name for the attribute state:
-    #     .human_status  # => 'Pending Activation'
+    # - list the human name for the attribute state:
+    #     .human_status  #=> 'Pending Activation'
     #
-    # * is a particular state set:
-    #     .pending?   # => false
-    #     .active?    # => true
-    #     .archived?  # => false
+    # - is a particular state set:
+    #     .pending?   #=> false
+    #     .active?    #=> true
+    #     .archived?  #=> false
     #
-    # * is a particular state not set:
-    #     .not_pending?   # => true
-    #     .not_active?    # => false
-    #     .not_archived?  # => true
+    # - is a particular state not set:
+    #     .not_pending?   #=> true
+    #     .not_active?    #=> false
+    #     .not_archived?  #=> true
     #
-    # * list the allowed transitions for the current state.
-    #     .status_transitions  # => [:suspended, :archived]
+    # - list the allowed transitions for the current state.
+    #     .status_transitions  #=> [:suspended, :archived]
     #
     module StateMethods
 
@@ -46,25 +46,27 @@ module StateGate
       # ======================================================================
       private
 
+      ##
       # Add Class and instance methods that allow querying states
       #
-      def generate_state_methods
-        add_state_attribute_methods
-        add_state_alias_methods
+      def _generate_state_methods
+        _add_state_attribute_methods
+        _add_state_alias_methods
       end
 
 
 
+      ##
       # add attribute methods
       #
-      def add_state_attribute_methods
+      def _add_state_attribute_methods
         _add__klass__attrs
         _add__klass__human_attrs
         _add__klass__attrs_for_select
 
         _add__instance__attrs
         _add__instance__human_attrs
-        _add__instance__human_attr        
+        _add__instance__human_attr
         _add__instance__state?
         _add__instance__not_state?
         _add__instance__attrs_for_select
@@ -72,9 +74,10 @@ module StateGate
 
 
 
+      ##
       # add alias methods
       #
-      def add_state_alias_methods
+      def _add_state_alias_methods
         return unless @alias
 
         _add__klass__attrs(@alias)
@@ -92,14 +95,19 @@ module StateGate
       #  Class Merthods
       # ======================================================================
 
+      ##
       # Adds a Class method to return an Array of the defined states for the attribute
-      #   eg:
-      #       Klass.statuses   # => [:pending, :active, :suspended, :archived]
+      #
+      # @param [Symbol] method_name
+      #   the name for the new method
+      #
+      # @example
+      #   Klass.statuses   #=> [:pending, :active, :suspended, :archived]
       #
       def _add__klass__attrs(method_name = @attribute)
         method_name = method_name.to_s.pluralize
 
-        add__klass__helper_method(method_name, __FILE__, __LINE__ - 2, %(
+        _add__klass__helper_method(method_name, __FILE__, __LINE__ - 2, %(
           def #{method_name}
             stateables[:#{@attribute}].states
           end
@@ -108,16 +116,21 @@ module StateGate
 
 
 
+      ##
       # Adds a Class method to return an Array of the human names of the defined states
       # for the attribute
-      #   eg:
-      #       Klass.human_statuses   # => ['Pending Activation', 'Active',
-      #                                    'Suspended by Admin', 'Archived']
+      #
+      # @param [Symbol] method_name
+      #   the name for the new method
+      #
+      # @example
+      #   Klass.human_statuses   #=> ['Pending Activation', 'Active',
+      #                                'Suspended by Admin', 'Archived']
       #
       def _add__klass__human_attrs(method_name = @attribute)
         method_name = "human_#{method_name.to_s.pluralize}"
 
-        add__klass__helper_method(method_name, __FILE__, __LINE__ - 2, %(
+        _add__klass__helper_method(method_name, __FILE__, __LINE__ - 2, %(
           def #{method_name}
             stateables[:#{@attribute}].human_states
           end
@@ -126,30 +139,36 @@ module StateGate
 
 
 
+      ##
       # Adds a Class method to return an Array of the human and state names for the
       # attribute, suitable for using in a form select statement.
       #
-      # sorted - if TRUE, the array is sorted in alphabetical order by human name
-      #          otherwise it is in the order specified
+      # @param [Symbol] method_name
+      #   the name for the new method
+      #
+      # @option method_name sorted
+      #   if TRUE, the array is sorted in alphabetical order by human name
+      #   otherwise it is in the order specified
       #
-      #   Klass.statuses_for_select         # => [ ['Pending Activation', 'pending'],
+      # @example
+      #   Klass.statuses_for_select         #=> [ ['Pending Activation', 'pending'],
       #                                            ['Active', 'active'],
       #                                            ['Suspended by Admin', 'suspended',
       #                                            ['Archived', 'archived'] ]
       #
-      #   Klass.statuses_for_select(true)   # => [ ['Active', 'active'],
+      #   Klass.statuses_for_select(true)   #=> [ ['Active', 'active'],
       #                                            ['Pending Activation', 'pending'],
       #                                            ['Suspended by Admin', 'suspended',
       #                                            ['Archived', 'archived'] ]
       #
-      # Note:
-      #       States should NEVER be set from direct user selection. This method is
-      #       intended for use within search forms, where the user may filter by state.
+      # @note
+      #   States should NEVER be set from direct user selection. This method is
+      #   intended for use within search forms, where the user may filter by state.
       #
       def _add__klass__attrs_for_select(method_name = @attribute)
         method_name = "#{method_name.to_s.pluralize}_for_select"
 
-        add__klass__helper_method(method_name, __FILE__, __LINE__ - 2, %(
+        _add__klass__helper_method(method_name, __FILE__, __LINE__ - 2, %(
           def #{method_name}(sorted = false)
             stateables[:#{@attribute}].states_for_select(sorted)
           end
@@ -162,14 +181,19 @@ module StateGate
       #  Instance Methods
       # ======================================================================
 
+      ##
       # Adds an Instance method to return Array of the defined states for the attribute
-      #   eg:
-      #       .statuses   # => [:pending, :active, :suspended, :archived]
+      #
+      # @param [Symbol] method_name
+      #   the name for the new method
+      #
+      # @example
+      #   .statuses   #=> [:pending, :active, :suspended, :archived]
       #
       def _add__instance__attrs(method_name = @attribute)
         method_name = method_name.to_s.pluralize
 
-        add__instance__helper_method(method_name, __FILE__, __LINE__ - 2, %(
+        _add__instance__helper_method(method_name, __FILE__, __LINE__ - 2, %(
           def #{method_name}
             stateables[:#{@attribute}].states
           end
@@ -178,15 +202,20 @@ module StateGate
 
 
 
+      ##
       # Adds an Instance method to return an Array of the human names for the attribute
-      #   eg:
-      #       .status_human_states   # => ['Pending Activation', 'Active',
-      #                                    'Suspended by Admin', 'Archived']
+      #
+      # @param [Symbol] method_name
+      #   the name for the new method
+      #
+      # @example
+      #   .status_human_states   #=> ['Pending Activation', 'Active',
+      #                                'Suspended by Admin', 'Archived']
       #
       def _add__instance__human_attrs(method_name = @attribute)
         method_name = "human_#{method_name.to_s.pluralize}"
 
-        add__instance__helper_method(method_name, __FILE__, __LINE__ - 2, %(
+        _add__instance__helper_method(method_name, __FILE__, __LINE__ - 2, %(
           def #{method_name}
             stateables[:#{@attribute}].human_states
           end
@@ -197,12 +226,12 @@ module StateGate
 
       # Adds an Instance method to return the human name for the attribute's state
       #   eg:
-      #       .human_status   # => 'Suspended by Admin'
+      #       .human_status   #=> 'Suspended by Admin'
       #
       def _add__instance__human_attr(method_name = @attribute)
         method_name = "human_#{method_name.to_s}"
 
-        add__instance__helper_method(method_name, __FILE__, __LINE__ - 2, %(
+        _add__instance__helper_method(method_name, __FILE__, __LINE__ - 2, %(
           def #{method_name}
             stateables[:#{@attribute}].human_state_for(#{@attribute})
           end
@@ -211,17 +240,19 @@ module StateGate
 
 
 
+      ##
       # Adds an Instance method for each state, returning TRUE if the state is set
-      #   eg:
-      #     --> when :active
-      #       .active?     # => true
-      #       .archived?   # => false
+      #
+      # @example
+      #   --> when :active
+      #   .active?     #=> true
+      #   .archived?   #=> false
       #
       def _add__instance__state?
         @engine.states.each do |state|
           method_name = "#{@engine.scope_name_for_state(state)}?"
 
-          add__instance__helper_method(method_name, __FILE__, __LINE__ - 3, %(
+          _add__instance__helper_method(method_name, __FILE__, __LINE__ - 3, %(
             def #{method_name}
               self[:#{@attribute}] == :#{state}.to_s
             end
@@ -231,20 +262,19 @@ module StateGate
 
 
 
+      ##
       # Adds an Instance method for each state, returning TRUE if the state is not set.
-      #   eg:
-      #     --> when :active
-      #       .not_active?     # => false
-      #       .not_archived?   # => true
       #
-      # def _add__instance__not_state?
-      #   attr_name = @attribute
+      # @example
+      #   --> when :active
+      #     .not_active?     #=> false
+      #     .not_archived?   #=> true
       #
       def _add__instance__not_state?
         @engine.states.each do |state|
           method_name = "not_#{@engine.scope_name_for_state(state)}?"
 
-          add__instance__helper_method(method_name, __FILE__, __LINE__ - 3, %(
+          _add__instance__helper_method(method_name, __FILE__, __LINE__ - 3, %(
             def #{method_name}
               self[:#{@attribute}] != :#{state}.to_s
             end
@@ -254,30 +284,36 @@ module StateGate
 
 
 
+      ##
       # Adds a, Instance method to return an Array of the human and state names for the
       # attribute, suitable for using in a form select statement.
       #
-      # sorted - if TRUE, the array is sorted in alphabetical order by human name
-      #          otherwise it is in the order specified
+      # @param [Symbol] method_name
+      #   the name for the new method
+      #
+      # @option method_name sorted
+      #   if TRUE, the array is sorted in alphabetical order by human name
+      #   otherwise it is in the order specified
       #
-      #   .statuses_for_select         # => [ ['Pending Activation', 'pending'],
+      # @example
+      #   .statuses_for_select         #=> [ ['Pending Activation', 'pending'],
       #                                       ['Active', 'active'],
       #                                       ['Suspended by Admin', 'suspended',
       #                                       ['Archived', 'archived'] ]
       #
-      #   .statuses_for_select(true)   # => [ ['Active', 'active'],
+      #   .statuses_for_select(true)   #=> [ ['Active', 'active'],
       #                                       ['Pending Activation', 'pending'],
       #                                       ['Suspended by Admin', 'suspended',
       #                                       ['Archived', 'archived'] ]
       #
-      # Note:
-      #       States should NEVER be set from direct user selection. This method is
-      #       intended for use within search forms, where the user may filter by state.
+      # @note
+      #   States should NEVER be set from direct user selection. This method is
+      #   intended for use within search forms, where the user may filter by state.
       #
       def _add__instance__attrs_for_select(method_name = @attribute)
         method_name = "#{method_name.to_s.pluralize}_for_select"
 
-        add__instance__helper_method(method_name, __FILE__, __LINE__ - 2, %(
+        _add__instance__helper_method(method_name, __FILE__, __LINE__ - 2, %(
           def #{method_name}(sorted = false)
             stateables[:#{@attribute}].states_for_select(sorted)
          end

data/lib/state_gate/builder/transition_methods.rb

@@ -8,21 +8,21 @@ module StateGate
     # Multiple private methods allowing StateGate::Builder to generate
     # transition methods.
     #
-    # * query the class for all allowed transitions:
-    #     Klass.status_transitions  # =>  { pending:   [:active],
-    #                               #       active:    [:suspended, :archived],
-    #                               #       suspended: [:active, :archived],
-    #                               #       archived:  [] }
+    # - query the class for all allowed transitions:
+    #     Klass.status_transitions  #=>  { pending:   [:active],
+    #                                      active:    [:suspended, :archived],
+    #                                      suspended: [:active, :archived],
+    #                                      archived:  [] }
     #
-    # * query the class for the allowed transitions for the given state:
-    #     Klass.status_transitions_for(:pending)  # =>  [:active]
-    #     Klass.status_transitions_for(:active)   # =>  [:suspended, :archived]
+    # - query the class for the allowed transitions for the given state:
+    #     Klass.status_transitions_for(:pending)  #=>  [:active]
+    #     Klass.status_transitions_for(:active)   #=>  [:suspended, :archived]
     #
-    # * list the allowed transitions from the current state:
-    #     .status_transitions  # =>  [:suspended, :archived]
+    # - list the allowed transitions from the current state:
+    #     .status_transitions  #=>  [:suspended, :archived]
     #
-    # * query if a given transition is allowed from the current state:
-    #     .status_transitions_to?(:active)  # =>  true
+    # - query if a given transition is allowed from the current state:
+    #     .status_transitions_to?(:active)  #=>  true
     #
     module TransitionMethods
 
@@ -32,9 +32,10 @@ module StateGate
 
 
 
+      ##
       # Add instance methods to the klass that query the allowed transitions
       #
-      def generate_transition_methods
+      def _generate_transition_methods
         _add__klass__attr_transitions
         _add__klass__attr_transitions_for
 
@@ -56,17 +57,22 @@ module StateGate
       #  Class methods
       # ======================================================================
 
+      ##
       # Adds a Class method to return a Hash of the allowed transitions for the attribte
-      #   eg:
-      #       Klass.status_transitions  # =>  { pending:   [:active],
-      #                                         active:    [:suspended, :archived],
-      #                                         suspended: [:active, :archived],
-      #                                         archived:  [] }
+      #
+      # @param [Symbol] method_name
+      #   the name for the new method
+      #
+      # @example
+      #   Klass.status_transitions  #=>  { pending:   [:active],
+      #                                     active:    [:suspended, :archived],
+      #                                     suspended: [:active, :archived],
+      #                                     archived:  [] }
       #
       def _add__klass__attr_transitions(method_name = @attribute)
         method_name = "#{method_name}_transitions"
 
-        add__klass__helper_method(method_name, __FILE__, __LINE__ - 2, %(
+        _add__klass__helper_method(method_name, __FILE__, __LINE__ - 2, %(
           def #{method_name}
             stateables[:#{@attribute}].transitions
           end
@@ -75,17 +81,22 @@ module StateGate
 
 
 
+      ##
       # Adds a Class method to return an Array of the allowed attribute transitions for
       # the provided state.
-      #   eg:
-      #       Klass.status_transitions_for(:pending) # =>  [:active]
-      #       Klass.status_transitions_for(:active)  # =>  [:suspended, :archived]
-      #       Klass.status_transitions_for(:dummy)   # =>  ArgumentError
+      #
+      # @param [Symbol] method_name
+      #   the name for the new method
+      #
+      # @example
+      #   Klass.status_transitions_for(:pending) #=>  [:active]
+      #   Klass.status_transitions_for(:active)  #=>  [:suspended, :archived]
+      #   Klass.status_transitions_for(:dummy)   #=>  ArgumentError
       #
       def _add__klass__attr_transitions_for(method_name = @attribute)
         method_name = "#{method_name}_transitions_for"
 
-        add__klass__helper_method(method_name, __FILE__, __LINE__ - 2, %(
+        _add__klass__helper_method(method_name, __FILE__, __LINE__ - 2, %(
           def #{method_name}(state)
             stateables[:#{@attribute}].transitions_for_state(state)
           end
@@ -99,17 +110,22 @@ module StateGate
       # ======================================================================
 
 
+      ##
       # Adds an instance method to return an Array of the allowed transitions from
       # the current attribute state.
-      #   eg:
-      #       .status_transitions  # =>  [:active]
-      #       .status_transitions  # =>  [:suspended, :archived]
-      #       .status_transitions  # =>  []
+      #
+      # @param [Symbol] method_name
+      #   the name for the new method
+      #
+      # @example
+      #   .status_transitions  #=>  [:active]
+      #   .status_transitions  #=>  [:suspended, :archived]
+      #   .status_transitions  #=>  []
       #
       def _add__instance__attr_transitions(method_name = @attribute)
         method_name = "#{method_name}_transitions"
 
-        add__instance__helper_method(method_name, __FILE__, __LINE__ - 2, %(
+        _add__instance__helper_method(method_name, __FILE__, __LINE__ - 2, %(
           def #{method_name}
             stateables[:#{@attribute}].transitions_for_state(self[:#{@attribute}])
           end
@@ -118,17 +134,21 @@ module StateGate
 
 
 
-
+      ##
       # Adds an instance method to return TRUE if the current attribute state can
       # transition to the queries status.
-      #   eg:
-      #       .status_transitions_to?(:active)    # =>  true
-      #       .status_transitions_to?(:archived)  # =>  false
+      #
+      # @param [Symbol] method_name
+      #   the name for the new method
+      #
+      # @example
+      #   .status_transitions_to?(:active)    #=>  true
+      #   .status_transitions_to?(:archived)  #=>  false
       #
       def _add__instance__attr_transitions_to(method_name = @attribute)
         method_name = "#{method_name}_transitions_to?"
 
-        add__instance__helper_method(method_name, __FILE__, __LINE__ - 2, %(
+        _add__instance__helper_method(method_name, __FILE__, __LINE__ - 2, %(
           def #{method_name}(query_state)
             test_state = StateGate.symbolize(query_state)
             stateables[:#{@attribute}].transitions_for_state(self[:#{@attribute}])