Add many examples to assertion documentation. Closes #7803 [jeremymcanally]

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

1 files changed, 24 insertions, 11 deletions

diff --git a/actionpack/lib/action_controller/assertions/tag_assertions.rb b/actionpack/lib/action_controller/assertions/tag_assertions.rb
index f8d2ec9798..4ac489520a 100644
--- a/actionpack/lib/action_controller/assertions/tag_assertions.rb
+++ b/actionpack/lib/action_controller/assertions/tag_assertions.rb
@@ -3,6 +3,7 @@ require 'html/document'
 
 module ActionController
   module Assertions
+    # Pair of assertions to testing elements in the HTML output of the response.
     module TagAssertions
       # Asserts that there is a tag/node/element in the body of the response
       # that meets all of the given conditions. The +conditions+ parameter must
@@ -48,39 +49,39 @@ module ActionController
       # * if the condition is +true+, the value must not be +nil+.
       # * if the condition is +false+ or +nil+, the value must be +nil+.
       #
-      # Usage:
+      # === Examples
       #
-      #   # assert that there is a "span" tag
+      #   # Assert that there is a "span" tag
       #   assert_tag :tag => "span"
       #
-      #   # assert that there is a "span" tag with id="x"
+      #   # Assert that there is a "span" tag with id="x"
       #   assert_tag :tag => "span", :attributes => { :id => "x" }
       #
-      #   # assert that there is a "span" tag using the short-hand
+      #   # Assert that there is a "span" tag using the short-hand
       #   assert_tag :span
       #
-      #   # assert that there is a "span" tag with id="x" using the short-hand
+      #   # Assert that there is a "span" tag with id="x" using the short-hand
       #   assert_tag :span, :attributes => { :id => "x" }
       #
-      #   # assert that there is a "span" inside of a "div"
+      #   # Assert that there is a "span" inside of a "div"
       #   assert_tag :tag => "span", :parent => { :tag => "div" }
       #
-      #   # assert that there is a "span" somewhere inside a table
+      #   # Assert that there is a "span" somewhere inside a table
       #   assert_tag :tag => "span", :ancestor => { :tag => "table" }
       #
-      #   # assert that there is a "span" with at least one "em" child
+      #   # Assert that there is a "span" with at least one "em" child
       #   assert_tag :tag => "span", :child => { :tag => "em" }
       #
-      #   # assert that there is a "span" containing a (possibly nested)
+      #   # Assert that there is a "span" containing a (possibly nested)
       #   # "strong" tag.
       #   assert_tag :tag => "span", :descendant => { :tag => "strong" }
       #
-      #   # assert that there is a "span" containing between 2 and 4 "em" tags
+      #   # Assert that there is a "span" containing between 2 and 4 "em" tags
       #   # as immediate children
       #   assert_tag :tag => "span",
       #              :children => { :count => 2..4, :only => { :tag => "em" } } 
       #
-      #   # get funky: assert that there is a "div", with an "ul" ancestor
+      #   # Get funky: assert that there is a "div", with an "ul" ancestor
       #   # and an "li" parent (with "class" = "enum"), and containing a 
       #   # "span" descendant that contains text matching /hello world/
       #   assert_tag :tag => "div",
@@ -105,6 +106,18 @@ module ActionController
       
       # Identical to #assert_tag, but asserts that a matching tag does _not_
       # exist. (See #assert_tag for a full discussion of the syntax.)
+      #
+      # === Examples
+      #   # Assert that there is not a "div" containing a "p"
+      #   assert_no_tag :tag => "div", :descendant => { :tag => "p" }
+      #
+      #   # Assert that an unordered list is empty
+      #   assert_no_tag :tag => "ul", :descendant => { :tag => "li" }
+      #
+      #   # Assert that there is not a "p" tag with between 1 to 3 "img" tags
+      #   # as immediate children
+      #   assert_no_tag :tag => "p",
+      #              :children => { :count => 1..3, :only => { :tag => "img" } }
       def assert_no_tag(*opts)
         clean_backtrace do
           opts = opts.size > 1 ? opts.last.merge({ :tag => opts.first.to_s }) : opts.first