Collections automatically cache and fetch partials.

Collections can take advantage of `multi_read` if they render one template
and their partials begin with a cache call.

The cache call must correspond to either what the collections elements are
rendered as, or match the inferred name of the partial.

So with a notifications/_notification.html.erb template like:

```ruby
<% cache notification %>
  <%# ... %>
<% end %>
```

A collection would be able to use `multi_read` if rendered like:

```ruby
<%= render @notifications %>
<%= render partial: 'notifications/notification', collection: @notifications, as: :notification %>
```

1 files changed, 23 insertions, 0 deletions

diff --git a/actionview/lib/action_view/helpers/cache_helper.rb b/actionview/lib/action_view/helpers/cache_helper.rb
index 56b1c5049c..dec8c9cee9 100644
--- a/actionview/lib/action_view/helpers/cache_helper.rb
+++ b/actionview/lib/action_view/helpers/cache_helper.rb
@@ -110,6 +110,29 @@ module ActionView
       #   <%= some_helper_method(person) %>
       #
       # Now all you'll have to do is change that timestamp when the helper method changes.
+      #
+      # === Automatic Collection Caching
+      #
+      # When rendering collections such as:
+      #
+      #   <%= render @notifications %>
+      #   <%= render partial: 'notifications/notification', collection: @notifications %>
+      #
+      # If the notifications/_notification partial starts with a cache call like so:
+      #
+      #   <% cache notification do %>
+      #     <%= notification.name %>
+      #   <% end %>
+      #
+      # The collection can then automatically use any cached renders for that
+      # template by reading them at once instead of one by one.
+      #
+      # See ActionView::Template::Handlers::ERB.resource_cache_call_pattern for more
+      # information on what cache calls make a template eligible for this collection caching.
+      #
+      # The automatic cache multi read can be turned off like so:
+      #
+      #   <%= render @notifications, cache: false %>
       def cache(name = {}, options = nil, &block)
         if controller.perform_caching
           safe_concat(fragment_for(cache_fragment_name(name, options), options, &block))