Emphasize cacheable objects in guide and API docs [ci-skip]

Clarify to users what objects may be cached, and highlight the option used to cache default non-serializable data.

Purpose: Improving new-to-Rails users' experience, as this detail may not be obvious, costing them time and effort spent debugging.

Co-authored-by: Hartley McGuire <[email protected]>
Co-authored-by: Jonathan Hefner <[email protected]>
(cherry picked from commit de12c18)

Author: 3 people

activesupport/lib/active_support/cache.rb

@@ -141,14 +141,17 @@ def retrieve_store_class(store)
     # Some implementations may not support all methods beyond the basic cache
     # methods of +fetch+, +write+, +read+, +exist?+, and +delete+.
     #
-    # ActiveSupport::Cache::Store can store any serializable Ruby object.
+    # ActiveSupport::Cache::Store can store any Ruby object that is supported by
+    # its +coder+'s +dump+ and +load+ methods.
     #
     #   cache = ActiveSupport::Cache::MemoryStore.new
     #
     #   cache.read('city')   # => nil
     #   cache.write('city', "Duckburgh")
     #   cache.read('city')   # => "Duckburgh"
     #
+    #   cache.write('not serializable', Proc.new {}) # => TypeError
+    #
     # Keys are always translated into Strings and are case sensitive. When an
     # object is specified as a key and has a +cache_key+ method defined, this
     # method will be called to define the key.  Otherwise, the +to_param+

guides/source/caching_with_rails.md

@@ -278,7 +278,7 @@ simply be explicit in a comment, like:
 
 ### Low-Level Caching
 
-Sometimes you need to cache a particular value or query result instead of caching view fragments. Rails' caching mechanism works great for storing __any__ kind of information.
+Sometimes you need to cache a particular value or query result instead of caching view fragments. Rails' caching mechanism works great for storing any serializable information.
 
 The most efficient way to implement low-level caching is using the `Rails.cache.fetch` method. This method does both reading and writing to the cache. When passed only a single argument, the key is fetched and value from the cache is returned. If a block is passed, that block will be executed in the event of a cache miss. The return value of the block will be written to the cache under the given cache key, and that return value will be returned. In case of cache hit, the cached value will be returned without executing the block.
 
@@ -391,7 +391,7 @@ There are some common options that can be used by all cache implementations. The
 
 * `:race_condition_ttl` - This option is used in conjunction with the `:expires_in` option. It will prevent race conditions when cache entries expire by preventing multiple processes from simultaneously regenerating the same entry (also known as the dog pile effect). This option sets the number of seconds that an expired entry can be reused while a new value is being regenerated. It's a good practice to set this value if you use the `:expires_in` option.
 
-* `:coder` - This option allows to replace the default cache entry serialization mechanism by a custom one. The `coder` must respond to `dump` and `load`, and passing a custom coder disable automatic compression.
+* `:coder` - This option replaces the default cache entry serialization mechanism with a custom one. The `coder` must respond to `dump` and `load`, and passing a custom coder disables automatic compression.
 
 #### Connection Pool Options