state_gate 1.2.3 → 1.3.0

data/lib/state_gate/builder/transition_validation_methods.rb

@@ -8,58 +8,58 @@ module StateGate
     # Multiple private methods allowing StateGate::Builder to generate
     # attribute setter methods for transition validation.
     #
-    # * initializing the attribute with +Class.new+ :
-    #     Klass.new(status: :active)  # => ArgumentError
+    # - initializing the attribute with +Class.new+ :
+    #     Klass.new(status: :active)  #=> ArgumentError
     #
-    # * initializing the attribute with +Class.create+ :
-    #     Klass.create(status: :active)  # => ArgumentError
+    # - initializing the attribute with +Class.create+ :
+    #     Klass.create(status: :active)  #=> ArgumentError
     #
-    # * initializing the attribute with <tt>Class.create!</tt> :
-    #     Klass.create!(status: :active)  # => ArgumentError
+    # - initializing the attribute with <tt>Class.create!</tt> :
+    #     Klass.create!(status: :active)  #=> ArgumentError
     #
-    # * setting the attribute with +attr=+ :
-    #     .status = :active    # => :active
-    #     .status = :archived  # => ArgumentError
+    # - setting the attribute with +attr=+ :
+    #     .status = :active    #=> :active
+    #     .status = :archived  #=> ArgumentError
     #
-    # * setting the attribute with <tt>[:attr]=</tt> :
-    #     [:status] = :active    # => :active
-    #     [:status] = :archived  # => ArgumentError
+    # - setting the attribute with <tt>[:attr]=</tt> :
+    #     [:status] = :active    #=> :active
+    #     [:status] = :archived  #=> ArgumentError
     #
-    # * setting the attribute with <tt>attributes=</tt> :
-    #     .attrubutes = {status: :active}    # => :active
-    #     .attributes = {status: :archived } # => ArgumentError
+    # - setting the attribute with <tt>attributes=</tt> :
+    #     .attrubutes = {status: :active}    #=> :active
+    #     .attributes = {status: :archived } #=> ArgumentError
     #
-    # * setting the attribute with <tt>assign_attributes</tt> :
-    #     .assign_attrubutes(status: :active)    # => :active
-    #     .assign_attributes(status: :archived)  # => ArgumentError
+    # - setting the attribute with <tt>assign_attributes</tt> :
+    #     .assign_attrubutes(status: :active)    #=> :active
+    #     .assign_attributes(status: :archived)  #=> ArgumentError
     #
-    # * updating the attribute with <tt>Class.update</tt> :
-    #     Klass.update(instance.id, status: :active)    # => :active
-    #     Klass.update(instance.id, status: :archived)  # => ArgumentError
+    # - updating the attribute with <tt>Class.update</tt> :
+    #     Klass.update(instance.id, status: :active)    #=> :active
+    #     Klass.update(instance.id, status: :archived)  #=> ArgumentError
     #
-    # * updating the attribute with <tt>.update</tt> :
-    #     .update(status: :active)    # => :active
-    #     .update(status: :archived)  # => ArgumentError
+    # - updating the attribute with <tt>.update</tt> :
+    #     .update(status: :active)    #=> :active
+    #     .update(status: :archived)  #=> ArgumentError
     #
-    # * updating the attribute with <tt>.update_column</tt> :
-    #     .update_column(:status, :active)    # => :active
-    #     .update_column(:status, :archived)  # => ArgumentError
+    # - updating the attribute with <tt>.update_column</tt> :
+    #     .update_column(:status, :active)    #=> :active
+    #     .update_column(:status, :archived)  #=> ArgumentError
     #
-    # * updating the attribute with <tt>.update_columns</tt> :
-    #     .update_columns(status: :active)    # => :active
-    #     .update_columns(status: :archived)  # => ArgumentError
+    # - updating the attribute with <tt>.update_columns</tt> :
+    #     .update_columns(status: :active)    #=> :active
+    #     .update_columns(status: :archived)  #=> ArgumentError
     #
-    # * updating the attribute with <tt>.write_attribute</tt> :
-    #     .write_attribute(:status, :active)    # => :active
-    #     .write_attribute(:status, :archived)  # => ArgumentError
+    # - updating the attribute with <tt>.write_attribute</tt> :
+    #     .write_attribute(:status, :active)    #=> :active
+    #     .write_attribute(:status, :archived)  #=> ArgumentError
     #
     #
     # === | Forcing a change
     #
     # To force a status change that would otherwise be prohibited, preceed the
     # new state with +force_+ :
-    #   .status = :archived         # => ArgumentError
-    #   .status = :force_archived   # => :archived
+    #   .status = :archived         #=> ArgumentError
+    #   .status = :force_archived   #=> :archived
     #
     module TransitionValidationMethods
 
@@ -69,19 +69,20 @@ module StateGate
 
 
 
+      ##
       # Add prepended instance methods to the klass that catch all methods for
       # updating the attribute and validated the new value is an allowed transition
       #
-      # Note:
-      #       These methods are only added if the engine has an
-      #       include_transition_validations? status on initialisation
+      # @note
+      #   These methods are only added if the engine has an
+      #   include_transition_validations? status on initialisation
       #
-      # Note:
-      #       The three methods "<atrr>=(val)", "write_attribute(<attr>, val)" and
-      #       "update_columns(<attr>: val)" cover all the possibilities of setting the
-      #       attribute through ActiveRecord.
+      # @note
+      #   The three methods "<atrr>=(val)", "write_attribute(<attr>, val)" and
+      #   "update_columns(<attr>: val)" cover all the possibilities of setting the
+      #   attribute through ActiveRecord.
       #
-      def generate_transition_validation_methods
+      def _generate_transition_validation_methods
         return if @engine.transitionless?
 
         _prepend__attribute_equals
@@ -96,13 +97,14 @@ module StateGate
       #  Prepend Module
       # ======================================================================
 
+      ##
       # Dynamically generated module to hold the validation setter methods
       # and is pre-pended to the class.
       #
       # A new module is create if it doesn't already exist.
       #
-      # Note:
-      #       the module is named "StateGate::<klass>TranstionValidationMethods"
+      # @note
+      #   the module is named "StateGate::<klass>TranstionValidationMethods"
       #
       def _transition_validation_module # rubocop:disable Metrics/MethodLength
         @_transition_validation_module ||= begin
@@ -125,16 +127,18 @@ module StateGate
       #  Instance methods
       # ======================================================================
 
+      ##
       # Adds a method to overwrite the attribute :<attr>=(val) setter, raising an error
       # if the supplied value is not a valid transition
-      #   eg:
-      #       .status = :archived  # => ArgumentError
-      #       .status - :active    # => :active
+      #
+      # @example
+      #   .status = :archived  #=> ArgumentError
+      #   .status - :active    #=> :active
       #
       # ==== actions
       #
-      # + assert it's a valid transition
-      # + call super
+      # - assert it's a valid transition
+      # - call super
       #
       def _prepend__attribute_equals
         attr_name = @attribute
@@ -150,18 +154,20 @@ module StateGate
 
 
 
+      ##
       # Adds a method to overwrite the instance :write_attribute(attr, val) setter,
       # raising an error if the supplied value is not a valid transition
-      #   eg:
-      #       .write_attribute(:status, :archived)  # => ArgumentError
-      #       .write_attribute(:status, :active)    # => :active
+      #
+      # @example
+      #   .write_attribute(:status, :archived)  #=> ArgumentError
+      #   .write_attribute(:status, :active)    #=> :active
       #
       # ==== actions
       #
-      # + loop through each attribute
-      # + get the base attribute name from any alias used
-      # + assert it's a valid transition
-      # + call super
+      # - loop through each attribute
+      # - get the base attribute name from any alias used
+      # - assert it's a valid transition
+      # - call super
       #
       def _prepend__write_attribute
         return if _transition_validation_module.method_defined?(:write_attribute)
@@ -180,18 +186,20 @@ module StateGate
 
 
 
+      ##
       # Adds a method to overwrite the instance :update_columns(attr: val) setter,
       # raising an error if the supplied value is not a valid transition
-      #   eg:
-      #       .update_columns(status: :archived)  # => ArgumentError
-      #       .update_columns(status: :active)    # => :active
+      #
+      # @example
+      #   .update_columns(status: :archived)  #=> ArgumentError
+      #   .update_columns(status: :active)    #=> :active
       #
       # ==== actions
       #
-      # + loop through each attribute
-      # + get the base attribute name from any alias used
-      # + assert it's a valid transition
-      # + call super
+      # - loop through each attribute
+      # - get the base attribute name from any alias used
+      # - assert it's a valid transition
+      # - call super
       #
       def _prepend__update_columns # rubocop:disable Metrics/MethodLength
         return if _transition_validation_module.method_defined?(:update_columns)
@@ -215,10 +223,12 @@ module StateGate
 
 
 
-      # Prepends an :itialize method to ensure the attribute is not set on initializing
+      ##
+      #Prepends an :itialize method to ensure the attribute is not set on initializing
       # a new instance unless :forced.
       #
-      #   Klass.new(status: :archived)  # => ArgumentError
+      # @example
+      #   Klass.new(status: :archived)  #=> ArgumentError
       #
       def _prepend__initialize # rubocop:disable Metrics/MethodLength
         return if _transition_validation_module.method_defined?(:initialize)

data/lib/state_gate/builder.rb

@@ -14,11 +14,11 @@ module StateGate
   #
   # Both Class and Instance methods are generated for:
   #
-  # * state interaction
-  # * state sequences
-  # * state scopes
-  # * transition interaction
-  # * transition validation
+  # - state interaction
+  # - state sequences
+  # - state scopes
+  # - transition interaction
+  # - transition validation
   #
   class Builder
 
@@ -35,24 +35,23 @@ module StateGate
     # ======================================================================
     private
 
+    ##
     # Initialize the Builder, creating the state gate and generating all the
     # Class and Instace helper methods on the sumbitted klass.
     #
-    # [:klass]
+    # @param [Class] klass
     #   The class containing the attribute to be cast as a state gate
-    #   (Class | required)
     #
-    # [:attribute_name]
-    #   The name of the klass attribute to use for the state gate
-    #   (Symbol | required)
+    # @param [Symbol] attribute_name
+    #   The name of the database attribute to use for the state gate
     #
-    # [:config]
+    # @block config
     #   The configuration block for the state gate.
-    #   (Block | required)
     #
-    #  StateGate::Builder.new(Klass, :attribute_name) do
+    # @example
+    #   StateGate::Builder.new(Klass, :attribute_name) do
     #       ... configuration ...
-    #  end
+    #   end
     #
     def initialize(klass = nil, attribute_name = nil, &config)
       @klass     = klass
@@ -70,19 +69,19 @@ module StateGate
       _cast_attribute_as_state_gate
 
       # generate the helper methods
-      generate_helper_methods
+      _generate_helper_methods
     end
 
 
 
     # Generate the helper methods
     #
-    def generate_helper_methods
+    def _generate_helper_methods
       # add the helper methods
-      generate_scope_methods
-      generate_state_methods
-      generate_transition_methods
-      generate_transition_validation_methods
+      _generate_scope_methods
+      _generate_state_methods
+      _generate_transition_methods
+      _generate_transition_validation_methods
 
       # warn if any state gate attribute methods are redefined
       _generate_method_redefine_detection
@@ -90,6 +89,7 @@ module StateGate
 
 
 
+    ##
     # Validate the klass to ensure it is a 'Class' and derived from ActiveRecord,
     # raising an error if not.
     #
@@ -100,15 +100,16 @@ module StateGate
 
 
 
+    ##
     # Parse the attribute name to ensure it is a valid input value and
     # detect if it's an attribute_alias.
     #
     # = meta
     #
-    # * ensure it exists
-    # * ensure it's a Symbol, to avoid string whitespace issues
-    # * check is it's a registere attribute
-    #   * update @attribute & @alias
+    # - ensure it exists
+    # - ensure it's a Symbol, to avoid string whitespace issues
+    # - check is it's a registere attribute
+    #   - update @attribute & @alias
     #
     def _parse_atttribute_name_for_alias
       if @attribute.nil?
@@ -125,6 +126,7 @@ module StateGate
 
 
 
+    ##
     # Validate we don't already have a state gate defined for the attribute,
     # raising an error if not.
     #
@@ -137,13 +139,14 @@ module StateGate
 
 
 
+    ##
     # Validate the attribute is a database String attribute,
     # raising an error if not.
     #
     # = meta
     #
-    # * ensure it's mapped to a database column
-    # * ensure it's a :string databse type
+    # - ensure it's mapped to a database column
+    # - ensure it's a :string databse type
     #
     def _assert_attribute_name_is_a_database_string_column
       if @klass.column_names.exclude?(@attribute.to_s)
@@ -157,10 +160,12 @@ module StateGate
 
 
 
+    ##
     # Builds a StateGate::Engine for the given attribute and add it to
     # the :stateables repository.
     #
-    # config - the user generated configuration for the engine, including states,
+    # @block config
+    #   the user generated configuration for the engine, including states,
     #           transitions and optional settings
     #
     def _build_state_gate_engine(&config)
@@ -171,6 +176,7 @@ module StateGate
 
 
 
+    ##
     # Adds a :stateables class_attribute if it doesn't already exist and
     # initializes it to an empty Hash.
     #
@@ -178,17 +184,16 @@ module StateGate
     # created when generating state gates. The state gate attribute name is used
     # as the key.
     #
-    # Example
-    #     Klass.stateables # => {
+    # @example
+    #     Klass.stateables #=> {
     #                                         status:   <StateGate::Engine>,
     #                                         account:  <StateGate::Engine>
     #                                       }
     #
-    # Note
-    #
-    # The default empty Hash is set after the attribute is created to accommodate
-    # ActiveRecord 5.0, even though ActiveRecord 6.0 allows it to be set within
-    # the .class_attribute method.
+    # @note
+    #   The default empty Hash is set after the attribute is created to accommodate
+    #   ActiveRecord 5.0, even though ActiveRecord 6.0 allows it to be set within
+    #   the .class_attribute method.
     #
     def _initialize_state_gate_repository
       return if @klass.methods(false).include?(:stateables)
@@ -199,6 +204,7 @@ module StateGate
 
 
 
+    ##
     # Builds a StateGate::Type with the custom states for the attribute,
     # then casts the attribute.
     #
@@ -208,9 +214,9 @@ module StateGate
     #
     # meta
     #
-    # * retrieve the root attribute name if the supplied attribute is an alias.
-    # * create a StateGate::Type with attributes states.
-    # * overwrite the attribute, casting the type as the new StateGate::Type
+    # - retrieve the root attribute name if the supplied attribute is an alias.
+    # - create a StateGate::Type with attributes states.
+    # - overwrite the attribute, casting the type as the new StateGate::Type
     #
     def _cast_attribute_as_state_gate
       states    = @engine.states
@@ -220,17 +226,21 @@ module StateGate
 
 
 
+    ##
     # Raise an ArgumentError for the given error, using I18n for the message.
     #
-    # err - Symbol key for the I18n message
-    #
-    # args - Hash of attributes to pass to the message string.
+    # @param [Symbol] err
+    #   the Symbol key for the I18n message
     #
-    #        [:klass] When true, args[:klass] will be updated with the 'KlassName'.
-    #        [:kattr] When true, args[:kattr] will be updated with 'KlassName#attribute'.
+    # @param [Hash] args
+    #   Hash of attributes to pass to the message string.
     #
-    # Example
+    # @option args :klass
+    #   When present, args[:klass] will be updated with the 'KlassName'.
+    # @option args :kattr
+    #   When true, args[:kattr] will be updated with 'KlassName#attribute'.
     #
+    # @example
     #     err(:invalid_attribute_type_err, kattr: true)
     #
     def err(err, **args)