Update layout and content_for documentation to use yield rather than magic @content_for instance variables.

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@4262 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

1 files changed, 7 insertions, 5 deletions

diff --git a/actionpack/lib/action_controller/layout.rb b/actionpack/lib/action_controller/layout.rb
index 7ecff73380..4e9e42d468 100644
--- a/actionpack/lib/action_controller/layout.rb
+++ b/actionpack/lib/action_controller/layout.rb
@@ -27,7 +27,7 @@ module ActionController #:nodoc:
     # that the header and footer are only mentioned in one place, like this:
     #
     #   <!-- The header part of this layout -->
-    #   <%= @content_for_layout %>
+    #   <%= yield %>
     #   <!-- The footer part of this layout -->
     #
     # And then you have content pages that look like this:
@@ -47,7 +47,7 @@ module ActionController #:nodoc:
     # references that won't materialize before rendering time:
     #
     #   <h1><%= @page_title %></h1>
-    #   <%= @content_for_layout %>
+    #   <%= yield %>
     #
     # ...and content pages that fulfill these references _at_ rendering time:
     #
@@ -159,10 +159,12 @@ module ActionController #:nodoc:
     #
     # As you can see, you pass the template as the first parameter, the status code as the second ("200" is OK), and the layout
     # as the third.
+    #
+    # NOTE: The old notation for rendering the view from a layout was to expose the magic <tt>@content_for_layout</tt> instance 
+    # variable. The preferred notation now is to use <tt>yield</tt>, as documented above.
     module ClassMethods
-      # If a layout is specified, all actions rendered through render and render_action will have their result assigned 
-      # to <tt>@content_for_layout</tt>, which can then be used by the layout to insert their contents with
-      # <tt><%= @content_for_layout %></tt>. This layout can itself depend on instance variables assigned during action
+      # If a layout is specified, all rendered actions will have their result rendered  
+      # when the layout<tt>yield</tt>'s. This layout can itself depend on instance variables assigned during action
       # performance and have access to them as any normal template would.
       def layout(template_name, conditions = {})
         add_layout_conditions(conditions)