Update render :partial documentation. Closes #5646.

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

2 files changed, 20 insertions, 14 deletions

diff --git a/actionpack/CHANGELOG b/actionpack/CHANGELOG
index 543cc3baa9..14ccf79009 100644
--- a/actionpack/CHANGELOG
+++ b/actionpack/CHANGELOG
@@ -1,5 +1,7 @@
 *SVN*
 
+* Update render :partial documentation. #5646 [matt@mattmargolis.net]
+
 * Integration tests behave well with render_component. #4632 [edward.frederick@revolution.com, dev.rubyonrails@maxdunn.com]
 
 * Added exception handling of missing layouts #5373 [chris@ozmm.org]
diff --git a/actionpack/lib/action_controller/base.rb b/actionpack/lib/action_controller/base.rb
index b90cf7f8bf..fb0a7b93d2 100755
--- a/actionpack/lib/action_controller/base.rb
+++ b/actionpack/lib/action_controller/base.rb
@@ -526,28 +526,32 @@ module ActionController #:nodoc:
       # <tt>render_with_layout("controller/action", status = 200, layout)</tt>.
       #
       # === Rendering partials
-      # 
-      # Partial rendering is most commonly used together with Ajax calls that only update one or a few elements on a page
+      #
+      # Partial rendering in a controller is most commonly used together with Ajax calls that only update one or a few elements on a page
       # without reloading. Rendering of partials from the controller makes it possible to use the same partial template in
       # both the full-page rendering (by calling it from within the template) and when sub-page updates happen (from the
       # controller action responding to Ajax calls). By default, the current layout is not used.
       #
-      #   # Renders the partial located at app/views/controller/_win.r(html|xml)
-      #   render :partial => "win"
+      #   # Renders the same partial with a local variable.
+      #   render :partial => "person", :locals => { :name => "david" }
       #
-      #   # Renders the partial with a status code of 500 (internal error)
-      #   render :partial => "broken", :status => 500
+      #   # Renders a collection of the same partial by making each element
+      #   # of @winners available through the local variable "person" as it
+      #   # builds the complete response.
+      #   render :partial => "person", :collection => @winners
       #
-      #   # Renders the same partial but also makes a local variable available to it
-      #   render :partial => "win", :locals => { :name => "david" }
+      #   # Renders the same collection of partials, but also renders the
+      #   # person_divider partial between each person partial.
+      #   render :partial => "person", :collection => @winners, :spacer_template => "person_divider"
       #
-      #   # Renders a collection of the same partial by making each element of @wins available through 
-      #   # the local variable "win" as it builds the complete response
-      #   render :partial => "win", :collection => @wins
+      #   # Renders a collection of partials located in a view subfolder
+      #   # outside of our current controller.  In this example we will be
+      #   # rendering app/views/shared/_note.r(html|xml)  Inside the partial
+      #   # each element of @new_notes is available as the local var "note".
+      #   render :partial => "shared/note", :collection => @new_notes
       #
-      #   # Renders the same collection of partials, but also renders the win_divider partial in between
-      #   # each win partial.
-      #   render :partial => "win", :collection => @wins, :spacer_template => "win_divider"
+      #   # Renders the partial with a status code of 500 (internal error).
+      #   render :partial => "broken", :status => 500
       #
       # Note that the partial filename must also be a valid Ruby variable name,
       # so e.g. 2005 and register-user are invalid.