Merge docrails

5 files changed, 32 insertions, 22 deletions

diff --git a/actionpack/lib/action_controller/assertions/selector_assertions.rb b/actionpack/lib/action_controller/assertions/selector_assertions.rb
index 7f8fe9ab19..0d56ea5ef7 100644
--- a/actionpack/lib/action_controller/assertions/selector_assertions.rb
+++ b/actionpack/lib/action_controller/assertions/selector_assertions.rb
@@ -109,20 +109,27 @@ module ActionController
       # starting from (and including) that element and all its children in
       # depth-first order.
       #
-      # If no element if specified, calling +assert_select+ will select from the
-      # response HTML. Calling #assert_select inside an +assert_select+ block will
-      # run the assertion for each element selected by the enclosing assertion.
+      # If no element if specified, calling +assert_select+ selects from the
+      # response HTML unless +assert_select+ is called from within an +assert_select+ block.
+      #
+      # When called with a block +assert_select+ passes an array of selected elements
+      # to the block. Calling +assert_select+ from the block, with no element specified,
+      # runs the assertion on the complete set of elements selected by the enclosing assertion.
+      # Alternatively the array may be iterated through so that +assert_select+ can be called
+      # separately for each element.
+      #
       #
       # ==== Example
-      #   assert_select "ol>li" do |elements|
+      # If the response contains two ordered lists, each with four list elements then:
+      #   assert_select "ol" do |elements|
       #     elements.each do |element|
-      #       assert_select element, "li"
+      #       assert_select element, "li", 4
       #     end
       #   end
       #
-      # Or for short:
-      #   assert_select "ol>li" do
-      #     assert_select "li"
+      # will pass, as will:
+      #   assert_select "ol" do
+      #     assert_select "li", 8
       #   end
       #
       # The selector may be a CSS selector expression (String), an expression
diff --git a/actionpack/lib/action_controller/flash.rb b/actionpack/lib/action_controller/flash.rb
index 9856dbed2a..56ee9c67e2 100644
--- a/actionpack/lib/action_controller/flash.rb
+++ b/actionpack/lib/action_controller/flash.rb
@@ -4,20 +4,22 @@ module ActionController #:nodoc:
   # action that sets <tt>flash[:notice] = "Successfully created"</tt> before redirecting to a display action that can
   # then expose the flash to its template. Actually, that exposure is automatically done. Example:
   #
-  #   class WeblogController < ActionController::Base
+  #   class PostsController < ActionController::Base
   #     def create
   #       # save post
   #       flash[:notice] = "Successfully created post"
-  #       redirect_to :action => "display", :params => { :id => post.id }
+  #       redirect_to posts_path(@post)
   #     end
   #
-  #     def display
+  #     def show
   #       # doesn't need to assign the flash notice to the template, that's done automatically
   #     end
   #   end
   #
-  #   display.erb
-  #     <% if flash[:notice] %><div class="notice"><%= flash[:notice] %></div><% end %>
+  #   show.html.erb
+  #     <% if flash[:notice] %>
+  #       <div class="notice"><%= flash[:notice] %></div>
+  #     <% end %>
   #
   # This example just places a string in the flash, but you can put any object in there. And of course, you can put as
   # many as you like at a time too. Just remember: They'll be gone by the time the next action has been performed.
diff --git a/actionpack/lib/action_controller/request.rb b/actionpack/lib/action_controller/request.rb
index cbbfca41f6..09dcd684e8 100755
--- a/actionpack/lib/action_controller/request.rb
+++ b/actionpack/lib/action_controller/request.rb
@@ -29,16 +29,18 @@ module ActionController
     HTTP_METHODS = %w(get head put post delete options)
     HTTP_METHOD_LOOKUP = HTTP_METHODS.inject({}) { |h, m| h[m] = h[m.upcase] = m.to_sym; h }
 
-    # The true HTTP request \method as a lowercase symbol, such as <tt>:get</tt>.
-    # UnknownHttpMethod is raised for invalid methods not listed in ACCEPTED_HTTP_METHODS.
+    # Returns the true HTTP request \method as a lowercase symbol, such as
+    # <tt>:get</tt>. If the request \method is not listed in the HTTP_METHODS
+    # constant above, an UnknownHttpMethod exception is raised.
     def request_method
       HTTP_METHOD_LOOKUP[super] || raise(UnknownHttpMethod, "#{super}, accepted HTTP methods are #{HTTP_METHODS.to_sentence}")
     end
     memoize :request_method
 
-    # The HTTP request \method as a lowercase symbol, such as <tt>:get</tt>.
-    # Note, HEAD is returned as <tt>:get</tt> since the two are functionally
-    # equivalent from the application's perspective.
+    # Returns the HTTP request \method used for action processing as a
+    # lowercase symbol, such as <tt>:post</tt>. (Unlike #request_method, this
+    # method returns <tt>:get</tt> for a HEAD request because the two are
+    # functionally equivalent from the application's perspective.)
     def method
       request_method == :head ? :get : request_method
     end
diff --git a/actionpack/lib/action_controller/routing.rb b/actionpack/lib/action_controller/routing.rb
index da9b56fdf9..a2141a77dc 100644
--- a/actionpack/lib/action_controller/routing.rb
+++ b/actionpack/lib/action_controller/routing.rb
@@ -193,9 +193,8 @@ module ActionController
   #
   #   map.connect '*path' , :controller => 'blog' , :action => 'unrecognized?'
   #
-  # will glob all remaining parts of the route that were not recognized earlier. This idiom
-  # must appear at the end of the path. The globbed values are in <tt>params[:path]</tt> in
-  # this case.
+  # will glob all remaining parts of the route that were not recognized earlier. 
+  # The globbed values are in <tt>params[:path]</tt> as an array of path segments.
   #
   # == Route conditions
   #
diff --git a/actionpack/lib/action_controller/session_management.rb b/actionpack/lib/action_controller/session_management.rb
index f06a0da75c..b556f04649 100644
--- a/actionpack/lib/action_controller/session_management.rb
+++ b/actionpack/lib/action_controller/session_management.rb
@@ -37,7 +37,7 @@ module ActionController #:nodoc:
 
       # Returns the hash used to configure the session. Example use:
       #
-      #   ActionController::Base.session_options[:session_secure] = true # session only available over HTTPS
+      #   ActionController::Base.session_options[:secure] = true # session only available over HTTPS
       def session_options
         @session_options ||= {}
       end