fix form_for example in ActionController::Resources documentation. Closes #7362 [gnarg], Added enhanced docs to routing assertions. Closes #7359 [Rob Sanheim], improve error message for Routing for named routes. Closes #7346 [Rob Sanheim]

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

1 files changed, 20 insertions, 4 deletions

diff --git a/actionpack/lib/action_controller/assertions/routing_assertions.rb b/actionpack/lib/action_controller/assertions/routing_assertions.rb
index 54a6dfc5a7..11a649c49a 100644
--- a/actionpack/lib/action_controller/assertions/routing_assertions.rb
+++ b/actionpack/lib/action_controller/assertions/routing_assertions.rb
@@ -3,13 +3,23 @@ module ActionController
     module RoutingAssertions
       # Asserts that the routing of the given path was handled correctly and that the parsed options match.
       #
-      #   assert_recognizes({:controller => 'items', :action => 'index'}, 'items')
+      #   assert_recognizes({:controller => 'items', :action => 'index'}, 'items') # check the default action
+      #   assert_recognizes({:controller => 'items', :action => 'list'}, 'items/list') # check a specific action
+      #   assert_recognizes({:controller => 'items', :action => 'list', :id => '1'}, 'items/list/1') # check an action with a parameter
       #
       # Pass a hash in the second argument to specify the request method.  This is useful for routes
-      # requiring a specific method.
+      # requiring a specific HTTP method.  The hash should contain a :path with the incoming request path
+      # 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})
       #
+      # 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" }) 
       def assert_recognizes(expected_options, path, extras={}, message=nil)
         if path.is_a? Hash
           request_method = path[:method]
@@ -33,7 +43,12 @@ module ActionController
         end
       end
 
-      # Asserts that the provided options can be used to generate the provided path.
+      # Asserts that the provided options can be used to generate the provided path.  This is the inverse of assert_recognizes.
+      # For example:
+      #
+      #   assert_generates("/items", :controller => "items", :action => "index")
+      #   assert_generates("/items/list", :controller => "items", :action => "list")
+      #   assert_generates("/items/list/1", { :controller => "items", :action => "list", :id => "1" }) 
       def assert_generates(expected_path, options, defaults={}, extras = {}, message=nil)
         clean_backtrace do 
           expected_path = "/#{expected_path}" unless expected_path[0] == ?/
@@ -53,7 +68,8 @@ module ActionController
       end
 
       # Asserts that path and options match both ways; in other words, the URL generated from 
-      # options is the same as path, and also that the options recognized from path are the same as options
+      # options is the same as path, and also that the options recognized from path are the same as options.  This
+      # essentially combines assert_recognizes and assert_generates into one step.
       def assert_routing(path, options, defaults={}, extras={}, message=nil)
         assert_recognizes(options, path, extras, message)