Document Serializer and FragmentCache

lib/active_model/serializer/adapter/fragment_cache.rb

@@ -10,12 +10,17 @@ module ActiveModel
           @serializer = serializer
         end
 
+        # TODO: Use Serializable::Resource
+        # TODO: call +constantize+ less
+        # 1. Create a CachedSerializer and NonCachedSerializer from the serializer class.
+        # 2. Serialize the above two with the given adapter.
+        # 3. Pass their serializations to the adapter +::fragment_cache+.
         def fetch
           klass = serializer.class
           # It will split the serializer into two, one that will be cached and other wont
           serializers = fragment_serializer(serializer.object.class.name, klass)
 
-          # Instanciate both serializers
+          # Instantiate both serializers
           cached_serializer     = serializers[:cached].constantize.new(serializer.object)
           non_cached_serializer = serializers[:non_cached].constantize.new(serializer.object)
 
@@ -36,6 +41,10 @@ module ActiveModel
 
         private
 
+        # Given a serializer class and a hash of its cached and non0cached serializers
+        # 1. Determine cached attributes from serializer class options.
+        # 2. Add cached attributes to cached Serializer.
+        # 3. Add non-cached attributes to non-cached Serializer
         def cached_attributes(klass, serializers)
           attributes            = serializer.class._attributes
           cached_attributes     = (klass._cache_only) ? klass._cache_only : attributes.reject { |attr| klass._cache_except.include?(attr) }
@@ -56,6 +65,23 @@ module ActiveModel
           end
         end
 
+        # Given a resource name and its serializer's class
+        # 1.  Dyanmically creates a CachedSerializer and NonCachedSerializer
+        #   for a given class 'name'.
+        # 2. Call
+        #       CachedSerializer.cache(serializer._cache_options)
+        #       CachedSerializer.fragmented(serializer)
+        #       NontCachedSerializer.cache(serializer._cache_options)
+        # 3. Build a hash keyed to the +cached+ and +non_cached+ serializers
+        # 4. Call +cached_attributes+ on the serializer class and the above hash
+        # 5. Return the hash
+        #
+        # @example
+        #   When +name+ is <tt>User::Admin</tt>
+        #   creates the Serializer classes (if they don't exist).
+        #     User_AdminCachedSerializer
+        #     User_AdminNOnCachedSerializer
+        #
         def fragment_serializer(name, klass)
           cached     = "#{to_valid_const_name(name)}CachedSerializer"
           non_cached = "#{to_valid_const_name(name)}NonCachedSerializer"