Add some documentation around internal APIs [ci skip]

While these method aren't public API, they are a non-trivial internal
API which warrant a bit of explanation.

1 files changed, 22 insertions, 0 deletions

diff --git a/activerecord/lib/active_record/attribute_decorators.rb b/activerecord/lib/active_record/attribute_decorators.rb
index 340dfe11cf..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