[ci skip] Document collection caching better.

Why are we here? Where did we come from? Where are we going... in 5 minutes?

These questions are not answered in this documentation. Instead collection
caching is better clarified. How it works, how it can share caches with
individual templates.

1 files changed, 15 insertions, 2 deletions

diff --git a/actionview/lib/action_view/helpers/cache_helper.rb b/actionview/lib/action_view/helpers/cache_helper.rb
index e842d8e31c..4c7c4b91c6 100644
--- a/actionview/lib/action_view/helpers/cache_helper.rb
+++ b/actionview/lib/action_view/helpers/cache_helper.rb
@@ -134,8 +134,21 @@ module ActionView
       #
       #   <%= render partial: 'notifications/notification', collection: @notifications, cached: true %>
       #
-      # The `cached: true` will make Action Views rendering issue a `read_multi` to
-      # the cache store instead of reading from it for every partial.
+      # The `cached: true` will make Action View's rendering read several templates
+      # from cache at once instead of one call per template.
+      #
+      # Templates in the collection not already cached are written to cache.
+      #
+      # Works great alongside individual template fragment caching.
+      # For instance if the template the collection renders is cached like:
+      #
+      #   # notifications/_notification.html.erb
+      #   <% cache notification do %>
+      #     <%# ... %>
+      #   <% end %>
+      #
+      # Any collection renders will find those cached templates when attempting
+      # to read multiple templates at once.
       def cache(name = {}, options = {}, &block)
         if controller.respond_to?(:perform_caching) && controller.perform_caching
           name_options = options.slice(:skip_digest, :virtual_path)