Refactor and document

lib/capybara/helpers.rb

@@ -4,7 +4,8 @@ module Capybara
 
   # @api private
   module Helpers
-    class << self
+    extend self
+
     ##
     #
     # Normalizes whitespace space by stripping leading and trailing
@@ -47,12 +48,18 @@ module Capybara
         html
       end
     end
-    end
-  end
 
-  # @api private
-  module CountHelpers
-    class << self
+    ##
+    #
+    # Checks if the given count matches the given count options. By default,
+    # when no options are given, count should be larger than zero.
+    #
+    # @param [Integer] count     The actual number. Should be coercible via Integer()
+    # @option [Range] between    Count must be within the given range
+    # @option [Integer] count    Count must be exactly this
+    # @option [Integer] maximum  Count must be smaller than or equal to this value
+    # @option [Integer] minimum  Count must be larger than or equal to this value
+    #
     def matches_count?(count, options={})
       case
       when options[:between]
@@ -68,6 +75,17 @@ module Capybara
       end
     end
 
+    ##
+    #
+    # Generates a failure message given a description of the query and count
+    # options.
+    #
+    # @param [String] description   Description of a query
+    # @option [Range] between       Count should have been within the given range
+    # @option [Integer] count       Count should have been exactly this
+    # @option [Integer] maximum     Count should have been smaller than or equal to this value
+    # @option [Integer] minimum     Count should have been larger than or equal to this value
+    #
     def failure_message(description, options={})
       message = "expected to find #{description}"
       if options[:count]
@@ -82,6 +100,16 @@ module Capybara
       message
     end
 
+    ##
+    #
+    # A poor man's `pluralize`. Given two declensions, one singular and one
+    # plural, as well as a count, this will pick the correct declension. This
+    # way we can generate gramatically correct error message.
+    #
+    # @param [String] singular     The singular form of the word
+    # @param [String] plural       The plural form of the word
+    # @param [Integer] count       The number of items
+    #
     def declension(singular, plural, count)
       if count == 1
         singular
@@ -91,4 +119,3 @@ module Capybara
     end
   end
 end
-end

lib/capybara/node/matchers.rb

@@ -462,11 +462,10 @@ module Capybara
 
       def text_found?(*args)
         type = args.shift if args.first.is_a?(Symbol) or args.first.nil?
-        content = args.shift
-        options = (args.first.is_a?(Hash))? args.first : {}
+        content, options = args
         count = Capybara::Helpers.normalize_whitespace(text(type)).scan(Capybara::Helpers.to_regexp(content)).count
 
-        Capybara::CountHelpers.matches_count?(count, options)
+        Capybara::Helpers.matches_count?(count, options || {})
       end
     end
   end

lib/capybara/result.rb

@@ -32,13 +32,13 @@ module Capybara
     def_delegators :@result, :each, :[], :at, :size, :count, :length, :first, :last, :empty?
 
     def matches_count?
-      Capybara::CountHelpers.matches_count?(@result.size, @query.options)
+      Capybara::Helpers.matches_count?(@result.size, @query.options)
     end
 
     def failure_message
-      message = Capybara::CountHelpers.failure_message(@query.description, @query.options)
+      message = Capybara::Helpers.failure_message(@query.description, @query.options)
       if count > 0
-        message << ", found #{count} #{Capybara::CountHelpers.declension("match", "matches", count)}: " << @result.map(&:text).map(&:inspect).join(", ")
+        message << ", found #{count} #{Capybara::Helpers.declension("match", "matches", count)}: " << @result.map(&:text).map(&:inspect).join(", ")
       else
         message << " but there were no matches"
       end

lib/capybara/rspec/matchers.rb

@@ -52,7 +52,7 @@ module Capybara
       end
 
       def failure_message_for_should
-        message = Capybara::CountHelpers.failure_message(description, options)
+        message = Capybara::Helpers.failure_message(description, options)
         message << " in #{format(@actual.text(type))}"
         message
       end