Add examples in the documentation for various assertions. Closes #9938 [zapnap]

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

4 files changed, 50 insertions, 5 deletions

diff --git a/actionpack/CHANGELOG b/actionpack/CHANGELOG
index 2ecee12d01..84f6cb08c2 100644
--- a/actionpack/CHANGELOG
+++ b/actionpack/CHANGELOG
@@ -1,5 +1,7 @@
 *SVN*
 
+* Add examples in the documentation for various assertions. Closes #9938 [zapnap]
+
 * When a NonInferrableControllerError is raised, make the proposed fix clearer in the error message. Closes #10199 [danger]
 
 * Update Prototype to 1.6.0.1.  [sam]
diff --git a/actionpack/lib/action_controller/assertions/dom_assertions.rb b/actionpack/lib/action_controller/assertions/dom_assertions.rb
index 0b8c78d9b3..5ffe5f1883 100644
--- a/actionpack/lib/action_controller/assertions/dom_assertions.rb
+++ b/actionpack/lib/action_controller/assertions/dom_assertions.rb
@@ -2,6 +2,12 @@ module ActionController
   module Assertions
     module DomAssertions
       # Test two HTML strings for equivalency (e.g., identical up to reordering of attributes)
+      #
+      # ==== Examples
+      #
+      #   # assert that the referenced method generates the appropriate HTML string
+      #   assert_dom_equal '<a href="http://www.example.com">Apples</a>', link_to("Apples", "http://www.example.com")
+      #
       def assert_dom_equal(expected, actual, message = "")
         clean_backtrace do
           expected_dom = HTML::Document.new(expected).root
@@ -13,6 +19,12 @@ module ActionController
       end
       
       # The negated form of +assert_dom_equivalent+.
+      #
+      # ==== Examples
+      #
+      #   # assert that the referenced method does not generate the specified HTML string
+      #   assert_dom_not_equal '<a href="http://www.example.com">Apples</a>', link_to("Oranges", "http://www.example.com")
+      #
       def assert_dom_not_equal(expected, actual, message = "")
         clean_backtrace do
           expected_dom = HTML::Document.new(expected).root
@@ -24,4 +36,4 @@ module ActionController
       end
     end
   end
-end
\ No newline at end of file
+end
diff --git a/actionpack/lib/action_controller/assertions/model_assertions.rb b/actionpack/lib/action_controller/assertions/model_assertions.rb
index 5fc5c81cb7..0b4313055a 100644
--- a/actionpack/lib/action_controller/assertions/model_assertions.rb
+++ b/actionpack/lib/action_controller/assertions/model_assertions.rb
@@ -2,6 +2,13 @@ module ActionController
   module Assertions
     module ModelAssertions
       # Ensures that the passed record is valid by ActiveRecord standards and returns any error messages if it is not.
+      #
+      # ==== Examples
+      #
+      #   # assert that a newly created record is valid
+      #   model = Model.new
+      #   assert_valid(model)
+      #
       def assert_valid(record)
         clean_backtrace do
           assert record.valid?, record.errors.full_messages.join("\n")
@@ -9,4 +16,4 @@ module ActionController
       end
     end
   end
-end
\ No newline at end of file
+end
diff --git a/actionpack/lib/action_controller/assertions/response_assertions.rb b/actionpack/lib/action_controller/assertions/response_assertions.rb
index 29eb2b033a..1ac0f234d4 100644
--- a/actionpack/lib/action_controller/assertions/response_assertions.rb
+++ b/actionpack/lib/action_controller/assertions/response_assertions.rb
@@ -14,6 +14,15 @@ module ActionController
       # You can also pass an explicit status number like assert_response(501)
       # or its symbolic equivalent assert_response(:not_implemented).
       # See ActionController::StatusCodes for a full list.
+      #
+      # ==== Examples
+      #
+      #   # assert that the response was a redirection
+      #   assert_response :redirect 
+      #
+      #   # assert that the response code was status code 401 (unauthorized)
+      #   assert_response 401
+      #
       def assert_response(type, message = nil)
         clean_backtrace do
           if [ :success, :missing, :redirect, :error ].include?(type) && @response.send("#{type}?")
@@ -28,9 +37,18 @@ module ActionController
         end
       end
 
-      # Assert that the redirection options passed in match those of the redirect called in the latest action. This match can be partial,
-      # such that assert_redirected_to(:controller => "weblog") will also match the redirection of
-      # redirect_to(:controller => "weblog", :action => "show") and so on.
+      # Assert that the redirection options passed in match those of the redirect called in the latest action. 
+      # This match can be partial, such that assert_redirected_to(:controller => "weblog") will also
+      # match the redirection of redirect_to(:controller => "weblog", :action => "show") and so on.
+      #
+      # ==== Examples
+      #
+      #   # assert that the redirection was to the "index" action on the WeblogController
+      #   assert_redirected_to :controller => "weblog", :action => "index"
+      #
+      #   # assert that the redirection was to the named route login_url
+      #   assert_redirected_to login_url
+      #
       def assert_redirected_to(options = {}, message=nil)
         clean_backtrace do
           assert_response(:redirect, message)
@@ -104,6 +122,12 @@ module ActionController
       end
 
       # Asserts that the request was rendered with the appropriate template file.
+      #
+      # ==== Examples
+      #
+      #   # assert that the "new" view template was rendered
+      #   assert_template "new"
+      #
       def assert_template(expected = nil, message=nil)
         clean_backtrace do
           rendered = expected ? @response.rendered_file(!expected.include?('/')) : @response.rendered_file