Merge docrails

6 files changed, 35 insertions, 33 deletions

diff --git a/actionpack/lib/action_controller/metal/responder.rb b/actionpack/lib/action_controller/metal/responder.rb
index cb0e600871..6178a59029 100644
--- a/actionpack/lib/action_controller/metal/responder.rb
+++ b/actionpack/lib/action_controller/metal/responder.rb
@@ -1,7 +1,7 @@
 module ActionController #:nodoc:
-  # Responder is responsible to expose a resource for different mime requests,
+  # Responder is responsible for exposing a resource to different mime requests,
   # usually depending on the HTTP verb. The responder is triggered when
-  # respond_with is called. The simplest case to study is a GET request:
+  # <code>respond_with</code> is called. The simplest case to study is a GET request:
   #
   #   class PeopleController < ApplicationController
   #     respond_to :html, :xml, :json
@@ -12,17 +12,17 @@ module ActionController #:nodoc:
   #     end
   #   end
   #
-  # When a request comes, for example with format :xml, three steps happen:
+  # When a request comes in, for example for an XML response, three steps happen:
   #
-  #   1) responder searches for a template at people/index.xml;
+  #   1) the responder searches for a template at people/index.xml;
   #
-  #   2) if the template is not available, it will invoke :to_xml in the given resource;
+  #   2) if the template is not available, it will invoke <code>#to_xml</code> on the given resource;
   #
-  #   3) if the responder does not respond_to :to_xml, call :to_format on it.
+  #   3) if the responder does not <code>respond_to :to_xml</code>, call <code>#to_format</code> on it.
   #
   # === Builtin HTTP verb semantics
   #
-  # Rails default responder holds semantics for each HTTP verb. Depending on the
+  # The default Rails responder holds semantics for each HTTP verb. Depending on the
   # content type, verb and the resource status, it will behave differently.
   #
   # Using Rails default responder, a POST request for creating an object could
@@ -55,7 +55,7 @@ module ActionController #:nodoc:
   #
   # === Nested resources
   #
-  # You can given nested resource as you do in form_for and polymorphic_url.
+  # You can supply nested resources as you do in <code>form_for</code> and <code>polymorphic_url</code>.
   # Consider the project has many tasks example. The create action for
   # TasksController would be like:
   #
@@ -67,15 +67,15 @@ module ActionController #:nodoc:
   #   end
   #
   # Giving an array of resources, you ensure that the responder will redirect to
-  # project_task_url instead of task_url.
+  # <code>project_task_url</code> instead of <code>task_url</code>.
   #
-  # Namespaced and singleton resources requires a symbol to be given, as in
+  # Namespaced and singleton resources require a symbol to be given, as in
   # polymorphic urls. If a project has one manager which has many tasks, it
   # should be invoked as:
   #
   #   respond_with(@project, :manager, @task)
   #
-  # Check polymorphic_url documentation for more examples.
+  # Check <code>polymorphic_url</code> documentation for more examples.
   #
   class Responder
     attr_reader :controller, :request, :format, :resource, :resources, :options
@@ -126,7 +126,7 @@ module ActionController #:nodoc:
       navigation_behavior(e)
     end
 
-    # All others formats follow the procedure below. First we try to render a
+    # All other formats follow the procedure below. First we try to render a
     # template, if the template is not available, we verify if the resource
     # responds to :to_format and display it.
     #
@@ -183,11 +183,11 @@ module ActionController #:nodoc:
       @default_response.call
     end
 
-    # display is just a shortcut to render a resource with the current format.
+    # Display is just a shortcut to render a resource with the current format.
     #
     #   display @user, :status => :ok
     #
-    # For xml request is equivalent to:
+    # For XML requests it's equivalent to:
     #
     #   render :xml => @user, :status => :ok
     #
@@ -204,14 +204,14 @@ module ActionController #:nodoc:
       controller.render given_options.merge!(options).merge!(format => resource)
     end
 
-    # Check if the resource has errors or not.
+    # Check whether the resource has errors.
     #
     def has_errors?
       resource.respond_to?(:errors) && !resource.errors.empty?
     end
 
-    # By default, render the :edit action for html requests with failure, unless
-    # the verb is post.
+    # By default, render the <code>:edit</code> action for HTML requests with failure, unless
+    # the verb is POST.
     #
     def default_action
       @action ||= ACTIONS_FOR_VERBS[request.method]
diff --git a/actionpack/lib/action_dispatch/routing.rb b/actionpack/lib/action_dispatch/routing.rb
index e99f979197..b598d6f7e2 100644
--- a/actionpack/lib/action_dispatch/routing.rb
+++ b/actionpack/lib/action_dispatch/routing.rb
@@ -193,9 +193,10 @@ module ActionDispatch
   #
   # With conditions you can define restrictions on routes. Currently the only valid condition is <tt>:method</tt>.
   #
-  # * <tt>:method</tt> - Allows you to specify which method can access the route. Possible values are <tt>:post</tt>,
-  #   <tt>:get</tt>, <tt>:put</tt>, <tt>:delete</tt> and <tt>:any</tt>. The default value is <tt>:any</tt>,
-  #   <tt>:any</tt> means that any method can access the route.
+  # * <tt>:method</tt> - Allows you to specify which HTTP method(s) can access the route. Possible values are
+  #   <tt>:post</tt>, <tt>:get</tt>, <tt>:put</tt>, <tt>:delete</tt> and <tt>:any</tt>. Use an array to specify more
+  #   than one method, e.g. <tt>[ :get, :post ]</tt>. The default value is <tt>:any</tt>, <tt>:any</tt> means that any
+  #   method can access the route.
   #
   # Example:
   #
diff --git a/actionpack/lib/action_dispatch/testing/assertions/routing.rb b/actionpack/lib/action_dispatch/testing/assertions/routing.rb
index fc477afb17..0c33539b4a 100644
--- a/actionpack/lib/action_dispatch/testing/assertions/routing.rb
+++ b/actionpack/lib/action_dispatch/testing/assertions/routing.rb
@@ -12,29 +12,29 @@ module ActionDispatch
       # and a :method containing the required HTTP verb.
       #
       #   # assert that POSTing to /items will call the create action on ItemsController
-      #   assert_recognizes {:controller => 'items', :action => 'create'}, {:path => 'items', :method => :post}
+      #   assert_recognizes({:controller => 'items', :action => 'create'}, {:path => 'items', :method => :post})
       #
       # You can also pass in +extras+ with a hash containing URL parameters that would normally be in the query string.  This can be used
       # to assert that values in the query string string will end up in the params hash correctly.  To test query strings you must use the
       # extras argument, appending the query string on the path directly will not work.  For example:
       #
       #   # assert that a path of '/items/list/1?view=print' returns the correct options
-      #   assert_recognizes {:controller => 'items', :action => 'list', :id => '1', :view => 'print'}, 'items/list/1', { :view => "print" }
+      #   assert_recognizes({:controller => 'items', :action => 'list', :id => '1', :view => 'print'}, 'items/list/1', { :view => "print" })
       #
       # The +message+ parameter allows you to pass in an error message that is displayed upon failure.
       #
       # ==== Examples
       #   # Check the default route (i.e., the index action)
-      #   assert_recognizes {:controller => 'items', :action => 'index'}, 'items'
+      #   assert_recognizes({:controller => 'items', :action => 'index'}, 'items')
       #
       #   # Test a specific action
-      #   assert_recognizes {:controller => 'items', :action => 'list'}, 'items/list'
+      #   assert_recognizes({:controller => 'items', :action => 'list'}, 'items/list')
       #
       #   # Test an action with a parameter
-      #   assert_recognizes {:controller => 'items', :action => 'destroy', :id => '1'}, 'items/destroy/1'
+      #   assert_recognizes({:controller => 'items', :action => 'destroy', :id => '1'}, 'items/destroy/1')
       #
       #   # Test a custom route
-      #   assert_recognizes {:controller => 'items', :action => 'show', :id => '1'}, 'view/item1'
+      #   assert_recognizes({:controller => 'items', :action => 'show', :id => '1'}, 'view/item1')
       #
       #   # Check a Simply RESTful generated route
       #   assert_recognizes list_items_url, 'items/list'
@@ -103,7 +103,7 @@ module ActionDispatch
       #  assert_routing '/home', :controller => 'home', :action => 'index'
       #
       #  # Test a route generated with a specific controller, action, and parameter (id)
-      #  assert_routing '/entries/show/23', :controller => 'entries', :action => 'show', id => 23
+      #  assert_routing '/entries/show/23', :controller => 'entries', :action => 'show', :id => 23
       #
       #  # Assert a basic route (controller + default action), with an error message if it fails
       #  assert_routing '/store', { :controller => 'store', :action => 'index' }, {}, {}, 'Route for store index not generated properly'
@@ -112,7 +112,7 @@ module ActionDispatch
       #  assert_routing 'controller/action/9', {:id => "9", :item => "square"}, {:controller => "controller", :action => "action"}, {}, {:item => "square"}
       #
       #  # Tests a route with a HTTP method
-      #  assert_routing { :method => 'put', :path => '/product/321' }, { :controller => "product", :action => "update", :id => "321" }
+      #  assert_routing({ :method => 'put', :path => '/product/321' }, { :controller => "product", :action => "update", :id => "321" })
       def assert_routing(path, options, defaults={}, extras={}, message=nil)
         assert_recognizes(options, path, extras, message)
 
diff --git a/actionpack/lib/action_view/helpers/form_tag_helper.rb b/actionpack/lib/action_view/helpers/form_tag_helper.rb
index 7688e786b1..048bedc7ba 100644
--- a/actionpack/lib/action_view/helpers/form_tag_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_tag_helper.rb
@@ -55,6 +55,9 @@ module ActionView
       # * Any other key creates standard HTML attributes for the tag.
       #
       # ==== Examples
+      #   select_tag "people", options_from_collection_for_select(@people, "name", "id")
+      #   # <select id="people" name="people"><option value="1">David</option></select>
+      #   
       #   select_tag "people", "<option>David</option>"
       #   # => <select id="people" name="people"><option>David</option></select>
       #
diff --git a/actionpack/lib/action_view/helpers/sanitize_helper.rb b/actionpack/lib/action_view/helpers/sanitize_helper.rb
index f03ffe5ef4..657d26f0a2 100644
--- a/actionpack/lib/action_view/helpers/sanitize_helper.rb
+++ b/actionpack/lib/action_view/helpers/sanitize_helper.rb
@@ -22,7 +22,7 @@ module ActionView
       #
       # Custom Use (only the mentioned tags and attributes are allowed, nothing else)
       #
-      #   <%= sanitize @article.body, :tags => %w(table tr td), :attributes => %w(id class style)
+      #   <%= sanitize @article.body, :tags => %w(table tr td), :attributes => %w(id class style) %>
       #
       # Add table tags to the default allowed tags
       #
diff --git a/actionpack/lib/action_view/helpers/text_helper.rb b/actionpack/lib/action_view/helpers/text_helper.rb
index be15e227b9..814d86812d 100644
--- a/actionpack/lib/action_view/helpers/text_helper.rb
+++ b/actionpack/lib/action_view/helpers/text_helper.rb
@@ -226,8 +226,7 @@ module ActionView
       # Returns the text with all the Textile[http://www.textism.com/tools/textile] codes turned into HTML tags.
       #
       # You can learn more about Textile's syntax at its website[http://www.textism.com/tools/textile].
-      # <i>This method is only available if RedCloth[http://whytheluckystiff.net/ruby/redcloth/]
-      # is available</i>.
+      # <i>This method is only available if RedCloth[http://redcloth.org/] is available</i>.
       #
       # ==== Examples
       #   textilize("*This is Textile!*  Rejoice!")
@@ -263,8 +262,7 @@ module ActionView
       # but without the bounding <p> tag that RedCloth adds.
       #
       # You can learn more about Textile's syntax at its website[http://www.textism.com/tools/textile].
-      # <i>This method is requires RedCloth[http://whytheluckystiff.net/ruby/redcloth/]
-      # to be available</i>.
+      # <i>This method is only available if RedCloth[http://redcloth.org/] is available</i>.
       #
       # ==== Examples
       #   textilize_without_paragraph("*This is Textile!*  Rejoice!")