Document AMS::Model::Caching

Author: bf4

lib/active_model_serializers/model.rb

@@ -5,6 +5,18 @@
 # Caching support is by-default mixed in when subclassing.
 # To disable mixing in any caching support,
 # set ActiveModelSerializers::Model.add_caching_support = false
+#
+# To generally use caching but have a noncaching subclass, you may:
+#     ActiveModelSerializers::Model.add_caching_support = false
+#     class NonCachingPoro < ActiveModelSerializers::Model
+#     end
+#     ActiveModelSerializers::Model.add_caching_support = true
+#
+# All sublasses of NonCachingPoro will have +add_caching_support+ false
+# while subclass of ActiveModelSerializers::Model will continue to mix in the
+# caching module.
+#
+# Future version of ActiveModelSerializers may change the default o make this simpler.
 module ActiveModelSerializers
   class Model
     include ActiveModel::Serializers::JSON
@@ -13,8 +25,11 @@ class Model
     autoload :Caching
 
     class_attribute :add_caching_support
+    # By default, include caching support methods in all subclasses.
     self.add_caching_support = true
     class_attribute :attribute_names
+    # Initialize +attribute_names+ for all subclasses.  The array is usually
+    # mutated in the +attributes+ method, but can be set directly, as well.
     self.attribute_names = []
 
     def self.attributes(*names)
@@ -39,6 +54,9 @@ def initialize(attributes = {})
       super
     end
 
+    # The the fields in +attribute_names+ determines the returned hash.
+    # +attributes+ are returned frozen to prevent any expectations that mutation affects
+    # the actual values in the model.
     def attributes
       attribute_names.each_with_object({}) do |attribute_name, result|
         result[attribute_name] = public_send(attribute_name).freeze

lib/active_model_serializers/model/caching.rb

@@ -4,19 +4,26 @@ module Caching
       extend ActiveSupport::Concern
 
       included do
+        # NOTE that +updated_at+ isn't included in +attribute_names+,
+        # which means it won't show up in +attributes+ unless a subclass has
+        # either <tt>attributes :updated_at</tt> which will redefine the methods
+        # or <tt>attribute_names << :updated_at</tt>.
         attr_writer :updated_at
+        # NOTE that +id+ will always be in +attributes+.
         attributes :id
       end
 
-      # Defaults to the downcased model name and updated_at
+      # To customize model behavior, this method must be redefined. However,
+      # there are other ways of setting the +cache_key+ a serializer uses.
       def cache_key
         ActiveSupport::Cache.expand_cache_key([
           self.class.model_name.name.downcase,
           "#{id}-#{updated_at.strftime('%Y%m%d%H%M%S%9N')}"
         ].compact)
       end
 
-      # Defaults to the time the serializer file was modified.
+      # When no set, defaults to the time the file was modified.
+      # See NOTE in included block.
       def updated_at
         defined?(@updated_at) ? @updated_at : File.mtime(__FILE__)
       end