1 files changed, 35 insertions, 13 deletions
diff --git a/activerecord/lib/active_record/attribute_decorators.rb b/activerecord/lib/active_record/attribute_decorators.rb
index 7d0ae32411..c39e9ce4c5 100644
--- a/activerecord/lib/active_record/attribute_decorators.rb
+++ b/activerecord/lib/active_record/attribute_decorators.rb
@@ -8,12 +8,34 @@ module ActiveRecord
     end
 
     module ClassMethods # :nodoc:
+      # This method is an internal API used to create class macros such as
+      # +serialize+, and features like time zone aware attributes.
+      #
+      # Used to wrap the type of an attribute in a new type.
+      # When the schema for a model is loaded, attributes with the same name as
+      # +column_name+ will have their type yielded to the given block. The
+      # return value of that block will be used instead.
+      #
+      # Subsequent calls where +column_name+ and +decorator_name+ are the same
+      # will override the previous decorator, not decorate twice. This can be
+      # used to create idempotent class macros like +serialize+
       def decorate_attribute_type(column_name, decorator_name, &block)
         matcher = ->(name, _) { name == column_name.to_s }
         key = "_#{column_name}_#{decorator_name}"
         decorate_matching_attribute_types(matcher, key, &block)
       end
 
+      # This method is an internal API used to create higher level features like
+      # time zone aware attributes.
+      #
+      # When the schema for a model is loaded, +matcher+ will be called for each
+      # attribute with its name and type. If the matcher returns a truthy value,
+      # the type will then be yielded to the given block, and the return value
+      # of that block will replace the type.
+      #
+      # Subsequent calls to this method with the same value for +decorator_name+
+      # will replace the previous decorator, not decorate twice. This can be
+      # used to ensure that class macros are idempotent.
       def decorate_matching_attribute_types(matcher, decorator_name, &block)
         reload_schema_from_cache
         decorator_name = decorator_name.to_s
@@ -24,13 +46,13 @@ module ActiveRecord
 
       private
 
-      def load_schema!
-        super
-        attribute_types.each do |name, type|
-          decorated_type = attribute_type_decorations.apply(name, type)
-          define_attribute(name, decorated_type)
+        def load_schema!
+          super
+          attribute_types.each do |name, type|
+            decorated_type = attribute_type_decorations.apply(name, type)
+            define_attribute(name, decorated_type)
+          end
         end
-      end
     end
 
     class TypeDecorator # :nodoc:
@@ -53,15 +75,15 @@ module ActiveRecord
 
       private
 
-      def decorators_for(name, type)
-        matching(name, type).map(&:last)
-      end
+        def decorators_for(name, type)
+          matching(name, type).map(&:last)
+        end
 
-      def matching(name, type)
-        @decorations.values.select do |(matcher, _)|
-          matcher.call(name, type)
+        def matching(name, type)
+          @decorations.values.select do |(matcher, _)|
+            matcher.call(name, type)
+          end
         end
-      end
     end
   end
 end