diff --git a/actionpack/lib/action_view/helpers/capture_helper.rb b/actionpack/lib/action_view/helpers/capture_helper.rb
index 20598237e9..edc6afc622 100644
--- a/actionpack/lib/action_view/helpers/capture_helper.rb
+++ b/actionpack/lib/action_view/helpers/capture_helper.rb
@@ -41,8 +41,11 @@ module ActionView
end
# Calling content_for stores a block of markup in an identifier for later use.
- # You can make subsequent calls to the stored content in other templates or the layout
- # by passing the identifier as an argument to yield.
+ # You can make subsequent calls to the stored content in other templates, helper modules
+ # or the layout by passing the identifier as an argument to content_for.
+ #
+ # Note: yield can still be used to retrieve the stored content, but calling
+ # yield doesn't work in helper modules, while content_for does.
#
# ==== Examples
#
@@ -50,11 +53,27 @@ module ActionView
# alert('You are not authorized to do that!')
# <% end %>
#
- # You can then use yield :not_authorized anywhere in your templates.
+ # You can then use content_for :not_authorized anywhere in your templates.
+ #
+ # <%= content_for :not_authorized if current_user.nil? %>
+ #
+ # This is equivalent to:
#
# <%= yield :not_authorized if current_user.nil? %>
#
- # You can also use this syntax alongside an existing call to yield in a layout. For example:
+ # content_for, however, can also be used in helper modules.
+ #
+ # module StorageHelper
+ # def stored_content
+ # content_for(:storage) || "Your storage is empty"
+ # end
+ # end
+ #
+ # This helper works just like normal helpers.
+ #
+ # <%= stored_content %>
+ #
+ # You can use the yield syntax alongside an existing call to yield in a layout. For example:
#
# <%# This is the layout %>
#
@@ -67,7 +86,7 @@ module ActionView
#
#