state_gate 1.2.3 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a3a28a8136472a91cd7c75616e189dd2c92a7b57a0bc18645395a46c55ff906
-  data.tar.gz: c909cd3d3a1101056ff1fe33ea6b94e38008f26a093476d7aaeb4ac17847b1ad
+  metadata.gz: c914825dceae121cfabc62d93c48e952d0d1ae4995bc0e477d1e2aa2e0cf9107
+  data.tar.gz: e49f5d7fd2517d88a7ae8c225baa452c75aa6cba94828e2e182fcb3462ffccec
 SHA512:
-  metadata.gz: 6b9cae6865505456fafa9da807e8472eb148f8af294c7631690b28ebba7b01c20e93f27b2bbe3ccf16c7ec27ea872e604726323bebb7639c7e7db726eb4bdd34
-  data.tar.gz: 7c104de800820cedee61c177a44504e2e1f052aaf529fd4990d3407ae337a4004c925f12162762f2db66b34a96ecda327e06e0c96c4dfc299feef63885b0e6f6
+  metadata.gz: 1042ce00609a2501647803fce1a41b689c45084726011c6f0f36e2498b9ca48110cf7d99160311eed74204f939255332be79894056098ccf2c1883dd88d0e6da
+  data.tar.gz: ba89c3bd3d36181c109ab56d5d9a6d8f68f735bfc645075d3dd16f2e8c7f829ff82746ef1db093f76743d05532159b864e75f78a4e960389d22c8ad818d76f84

data/lib/state_gate/builder/conflict_detection_methods.rb

@@ -14,54 +14,73 @@ module StateGate
       # ======================================================================
       private
 
+      ##
       # Check if a class method is already defined. Checks are made:
       # 1 --> is it an ActiveRecord dangerous method?
       # 2 --> is it an ActiveRecord defined class method?
       # 3 --> is it a singleton method of the klass?
       # 4 --> is it defined within any of the klass ancestors?
       #
-      # If found, raise an error giving a guide to where the method has been defined
+      # @param [Symbol] method_name
+      #   the class method name to test for conclict
       #
-      def detect_class_method_conflict!(method_name)
+      # @raise [ConflictError]
+      #   if the method name has already been defined
+      #
+      def _detect_class_method_conflict!(method_name)
         defining_klass = _active_record_protected_method?(method_name) ||
                          _klass_singleton_method?(method_name) ||
                          _klass_ancestor_singleton_method?(method_name)
 
         return unless defining_klass
 
-        raise_conflict_error method_name, type: 'a class', source: defining_klass
+        _raise_conflict_error method_name, type: 'a class', source: defining_klass
       end
 
 
 
+      ##
       # Check an instance method is already defined. Checks are made:
       # 1 --> is it an ActiveRecord dangerous method?
       # 2 --> is it an ActiveRecord defined instance method?
       # 3 --> is it an instance method of the klass?
       # 4 --> is it defined within any of the klass ancestors?
       #
-      # If found, raise an error giving a guide to where the method has been defined
+      # @param [Symbol] method_name
+      #   the instance method name to test for conclict
+      #
+      # @raise [ConflictError]
+      #   if the method name has already been defined
       #
-      def detect_instance_method_conflict!(method_name)
+      def _detect_instance_method_conflict!(method_name)
         defining_klass = _active_record_protected_method?(method_name) ||
                          _klass_instance_method?(method_name) ||
                          _klass_ancestor_instance_method?(method_name)
 
         return unless defining_klass
 
-        raise_conflict_error method_name, source: defining_klass
+        _raise_conflict_error method_name, source: defining_klass
       end
 
 
 
       # Raise a StateGate::ConflictError with a details message of the problem
       #
-      # = Message
+      # @param [Symbol] method_name
+      #   the method name
+      #
+      # @param [String] type
+      #   the optional definition of which type of errors this is: instance or class
       #
-      #           StateGate for Klass#attribute will generate a class
-      #           method 'statuses', which is already defined by ActiveRecord.
+      # @param [String] source
+      #   the optional class name
       #
-      def raise_conflict_error(method_name, type: 'an instance', source: 'ActiveRecord')
+      # @raise [ConflictError]
+      #   with the message:
+      #     StateGate for Klass#attribute will generate a class
+      #     method 'statuses', which is already defined by ActiveRecord.
+      #
+      def _raise_conflict_error(method_name, type: 'an instance', source: 'ActiveRecord')
         fail StateGate::ConflictError, I18n.t('state_gate.builder.conflict_err',
                                               klass:       @klass,
                                               attribute:   @attribute,
@@ -72,25 +91,37 @@ module StateGate
 
 
 
+      ##
       # Check if the method is an ActiveRecord dangerous method name
       #
-      def _active_record_protected_method?(method_name) #:nodoc:
+      # @param [Symbol] method_name
+      #   the method name
+      #
+      def _active_record_protected_method?(method_name)
         'ActiveRecord' if _dangerous_method_names.include?(method_name)
       end
 
 
 
+      ##
       # Check if the method is a singleton method of the klass
       #
-      def _klass_singleton_method?(method_name) #:nodoc:
+      # @param [Symbol] method_name
+      #   the method name
+      #
+      def _klass_singleton_method?(method_name)
         @klass.name if @klass.singleton_methods(false).include?(method_name.to_sym)
       end
 
 
 
+      ##
       # Check if the method is an ancestral singleton method of the klass
       #
-      def _klass_ancestor_singleton_method?(method_name) #:nodoc:
+      # @param [Symbol] method_name
+      #   the method name
+      #
+      def _klass_ancestor_singleton_method?(method_name)
         return nil unless @klass.respond_to?(method_name)
 
         @klass.singleton_class
@@ -101,17 +132,25 @@ module StateGate
 
 
 
+      ##
       # Check if the method an instance method of the klass
       #
-      def _klass_instance_method?(method_name) #:nodoc:
+      # @param [Symbol] method_name
+      #   the method name
+      #
+      def _klass_instance_method?(method_name)
         @klass.instance_methods(false).include?(method_name.to_sym) ? @klass.name : nil
       end
 
 
 
+      ##
       # Check if the method is an ancestral singleton method of the klass
       #
-      def _klass_ancestor_instance_method?(method_name) #:nodoc:
+      # @param [Symbol] method_name
+      #   the method name
+      #
+      def _klass_ancestor_instance_method?(method_name)
         return nil unless @klass.instance_methods.include?(method_name.to_sym)
 
         @klass.ancestors
@@ -121,9 +160,11 @@ module StateGate
 
 
 
-      # returns an array of dagerous methods names found in
-      # ActiveRecord::AttributeMethods::RESTRICTED_CLASS_METHODS (which is called
-      # BLACKLISTED_CLASS_METHODS in 5.0 and 5.1)
+      ##
+      # @return [Array[Symbol]]
+      #   array of dagerous methods names found in
+      #   ActiveRecord::AttributeMethods::RESTRICTED_CLASS_METHODS (which is called
+      #   BLACKLISTED_CLASS_METHODS in 5.0 and 5.1)
       #
       def _dangerous_method_names
         %w[private public protected allocate new name parent superclass]

data/lib/state_gate/builder/dynamic_module_creation_methods.rb

@@ -19,14 +19,15 @@ module StateGate
       # = Dynamic Module Creation
       # ======================================================================
 
+      ##
       # Dynamically generated module to hold the StateGate helper methods. This
       # keeps a clear distinction between the state machine helper methods and the klass'
       # own methods.
       #
       # The module is named after the class and is created if needed, or reused if exisitng.
       #
-      # Note:
-      #       the module is named "<klass>::StateGate_HelperMethods"
+      # @note
+      #   the module is named "<klass>::StateGate_HelperMethods"
       #
       def _helper_methods_module
         @_helper_methods_module ||= begin
@@ -46,6 +47,7 @@ module StateGate
       # ======================================================================
 
 
+      ##
       # Adds the hook method :method_added to the Klass, detecting any new method
       # definitions for an attribute already defined as a StateGate.
       #
@@ -54,16 +56,15 @@ module StateGate
       #
       # method_name - the name of the newly defined method.
       #
-      # Note
+      # @note
+      #   This method is added last so it does not trigger when StateGate adds
+      #   the attribute methods.
       #
-      # This method is added last so it does not trigger when StateGate adds
-      # the attribute methods.
+      # meta
       #
-      #  meta
-      #
-      # * loop though each state machine attribute.
-      #   * does the new defined method use 'attr' or 'attr='?
-      #     * if so then record an error logger if denied, othewise use `puts`
+      # - loop though each state machine attribute.
+      #   - does the new defined method use 'attr' or 'attr='?
+      #     - if so then record an error logger if denied, othewise use `puts`
       #
       def _generate_method_redefine_detection # rubocop:disable Metrics/MethodLength
         @klass.instance_eval(%(
@@ -89,29 +90,42 @@ module StateGate
       #   Method Creation
       # ======================================================================
 
+      ##
       # Add an Class helper method to the _helper_methods_module
       #
-      # method_name - a String name for the method, needed to check for conflicts
-      # file        - a String file name for error reporting
-      # line        - a String or Integer line number for error reporting
-      # method_body - a String to bhe evaluates in the module
+      # @param [String] method_name
+      #   name for the method to check for conflicts
+      #
+      # @param [String] file
+      #   file name for error reporting
+      #
+      # @param [String,Integer] line
+      #   line number for error reporting
+      #
+      # @param [String] method_body
+      #   a String to be evaluated in the module
       #
-      def add__klass__helper_method(method_name, file, line, method_body)
-        detect_class_method_conflict!(method_name)
+      def _add__klass__helper_method(method_name, file, line, method_body)
+        _detect_class_method_conflict!(method_name)
         @klass.instance_eval(method_body, file, line)
       end
 
 
 
+      ##
       # Add an instance helper method to the _helper_methods_module
       #
-      # method_name - a String name for the method, needed to check for conflicts
-      # file        - a String file name for error reporting
-      # line        - a String or Integer line number for error reporting
-      # method_body - a String to bhe evaluates in the module
+      # @param [String] method_name
+      #   name for the method to check for conflicts
+      # @param [String] file
+      #   file name for error reporting
+      # @param [String] line
+      #   line number for error reporting
+      # @param [String] method_body
+      #   a String to bhe evaluates in the module
       #
-      def add__instance__helper_method(method_name, file, line, method_body)
-        detect_instance_method_conflict!(method_name)
+      def _add__instance__helper_method(method_name, file, line, method_body)
+        _detect_instance_method_conflict!(method_name)
         _helper_methods_module.module_eval(method_body, file, line)
       end
 

data/lib/state_gate/builder/scope_methods.rb

@@ -8,14 +8,14 @@ module StateGate
     # Multiple private methods enabling StateGate::Builder to generate
     # scopes for each state.
     #
-    # * fetch all records with the given state:
-    #     Klass.active # => Klass.where(state: :active)
+    # - fetch all records with the given state:
+    #     Klass.active #=> Klass.where(state: :active)
     #
-    # * fetch all records without the given state:
-    #     Klass.not_active # => Klass.where.not(state: :active)
+    # - fetch all records without the given state:
+    #     Klass.not_active #=> Klass.where.not(state: :active)
     #
-    # * fetch all records with the supplied states:
-    #     Klass.with_statuses(:pending, :active) # => Klass.where(state: [:pending, :active])
+    # - fetch all records with the supplied states:
+    #     Klass.with_statuses(:pending, :active) #=> Klass.where(state: [:pending, :active])
     #
     module ScopeMethods
 
@@ -24,12 +24,13 @@ module StateGate
       private
 
 
+      ##
       # Add scopes to the klass for filtering by state
       #
-      # Note:
-      #       The scope name is a concatenation of <prefix><state name><suffix>
+      # @note
+      #   The scope name is a concatenation of <prefix><state name><suffix>
       #
-      def generate_scope_methods
+      def _generate_scope_methods
         return unless @engine.include_scopes?
 
         _add__klass__state_scopes
@@ -45,49 +46,58 @@ module StateGate
       #  Klass methods
       # ======================================================================
 
+      ##
       # Add a klass method that scopes records to the specified state.
-      #   eg:
-      #       Klass.active         # => ActiveRecord::Relation
-      #       Klass.active_status  # => ActiveRecord::Relation
+      #
+      # @example
+      #   Klass.active         #=> ActiveRecord::Relation
+      #   Klass.active_status  #=> ActiveRecord::Relation
       #
       def _add__klass__state_scopes
         attr_name = @attribute
 
         @engine.states.each do |state|
           scope_name = @engine.scope_name_for_state(state)
-          detect_class_method_conflict! scope_name
+          _detect_class_method_conflict! scope_name
           @klass.scope(scope_name, -> { where(attr_name => state) })
         end # each state
       end # _add__klass__state_scopes
 
 
 
+      ##
       # Add a klass method that scopes records to those without the specified state.
-      #   eg:
-      #       Klass.not_active         # => ActiveRecord::Relation
-      #       Klass.not_active_status  # => ActiveRecord::Relation
+      #
+      # @example
+      #   Klass.not_active         #=> ActiveRecord::Relation
+      #   Klass.not_active_status  #=> ActiveRecord::Relation
       #
       def _add__klass__not_state_scopes
         attr_name = @attribute
 
         @engine.states.each do |state|
           scope_name = @engine.scope_name_for_state(state)
-          detect_class_method_conflict! "not_#{scope_name}"
+          _detect_class_method_conflict! "not_#{scope_name}"
           @klass.scope "not_#{scope_name}", -> { where.not(attr_name => state) }
         end # each state
       end # _add__klass__not_state_scopes
 
 
 
+      ##
       # Add a klass method that scopes records to the given states.
-      #   eg:
-      #       Klass.with_statuses(:active, :pending) # => ActiveRecord::Relation
+      #
+      # @param [Symbol] method_name
+      #   the method name for the new scope
+      #
+      # @example
+      #   Klass.with_statuses(:active, :pending) #=> ActiveRecord::Relation
       #
       def _add__klass__with_attrs_scope(method_name = @attribute)
         attr_name   = @attribute
         method_name = "with_#{method_name.to_s.pluralize}"
 
-        detect_class_method_conflict! method_name
+        _detect_class_method_conflict! method_name
         @klass.scope method_name, ->(states) { where(attr_name => Array(states)) }
       end # _add__klass__with_attrs_scope