mocha 0.10.5 → 0.11.0

data/lib/mocha/parameter_matchers/not.rb

@@ -1,17 +1,23 @@
 require 'mocha/parameter_matchers/base'
 
 module Mocha
-  
+
   module ParameterMatchers
 
-    # :call-seq: Not(parameter_matcher) -> parameter_matcher
+    # Matches if +matcher+ does *not* match.
+    #
+    # @param [Base] matcher matcher whose logic to invert.
+    # @return [Not] parameter matcher.
+    #
+    # @see Expectation#with
     #
-    # Matches if +parameter_matcher+ does not match.
+    # @example Actual parameter does not include the value +1+.
     #   object = mock()
     #   object.expects(:method_1).with(Not(includes(1)))
     #   object.method_1([0, 2, 3])
     #   # no error raised
     #
+    # @example Actual parameter does include the value +1+.
     #   object = mock()
     #   object.expects(:method_1).with(Not(includes(1)))
     #   object.method_1([0, 1, 2, 3])
@@ -19,24 +25,28 @@ module Mocha
     def Not(matcher)
       Not.new(matcher)
     end
-    
-    class Not < Base # :nodoc:
-      
+
+    # Parameter matcher which inverts the logic of the specified matcher using a logical NOT operation.
+    class Not < Base
+
+      # @private
       def initialize(matcher)
         @matcher = matcher
       end
-    
+
+      # @private
       def matches?(available_parameters)
         parameter = available_parameters.shift
         !@matcher.matches?([parameter])
       end
-      
+
+      # @private
       def mocha_inspect
         "Not(#{@matcher.mocha_inspect})"
       end
-      
+
     end
-    
+
   end
-  
-end
+
+end

data/lib/mocha/parameter_matchers/object.rb

@@ -1,15 +1,17 @@
 require 'mocha/parameter_matchers/equals'
 
 module Mocha
-  
+
   module ObjectMethods
-    def to_matcher # :nodoc:
+    # @private
+    def to_matcher
       Mocha::ParameterMatchers::Equals.new(self)
     end
   end
-  
+
 end
 
+# @private
 class Object
   include Mocha::ObjectMethods
 end

data/lib/mocha/parameter_matchers/optionally.rb

@@ -1,25 +1,33 @@
 module Mocha
-  
+
   module ParameterMatchers
 
-    # :call-seq: optionally(*parameter_matchers) -> parameter_matcher
-    #
     # Matches optional parameters if available.
+    #
+    # @param [*Array<Base>] matchers matchers for optional parameters.
+    # @return [Optionally] parameter matcher.
+    #
+    # @see Expectation#with
+    #
+    # @example Only the two required parameters are supplied and they both match their expected value.
     #   object = mock()
     #   object.expects(:method_1).with(1, 2, optionally(3, 4))
     #   object.method_1(1, 2)
     #   # no error raised
     #
+    # @example Both required parameters and one of the optional parameters are supplied and they all match their expected value.
     #   object = mock()
     #   object.expects(:method_1).with(1, 2, optionally(3, 4))
     #   object.method_1(1, 2, 3)
     #   # no error raised
     #
+    # @example Both required parameters and both of the optional parameters are supplied and they all match their expected value.
     #   object = mock()
     #   object.expects(:method_1).with(1, 2, optionally(3, 4))
     #   object.method_1(1, 2, 3, 4)
     #   # no error raised
     #
+    # @example One of the actual optional parameters does not match the expected value.
     #   object = mock()
     #   object.expects(:method_1).with(1, 2, optionally(3, 4))
     #   object.method_1(1, 2, 3, 5)
@@ -27,13 +35,16 @@ module Mocha
     def optionally(*matchers)
       Optionally.new(*matchers)
     end
-    
-    class Optionally < Base # :nodoc:
-      
+
+    # Parameter matcher which allows optional parameters to be specified.
+    class Optionally < Base
+
+      # @private
       def initialize(*parameters)
         @matchers = parameters.map { |parameter| parameter.to_matcher }
       end
-      
+
+      # @private
       def matches?(available_parameters)
         index = 0
         while (available_parameters.length > 0) && (index < @matchers.length) do
@@ -43,13 +54,14 @@ module Mocha
         end
         return true
       end
-      
+
+      # @private
       def mocha_inspect
         "optionally(#{@matchers.map { |matcher| matcher.mocha_inspect }.join(", ") })"
       end
-      
+
     end
-    
+
   end
-  
-end
+
+end

data/lib/mocha/parameter_matchers/query_string.rb

@@ -4,14 +4,20 @@ require 'uri'
 module Mocha
   module ParameterMatchers
 
-    # :call-seq: has_equivalent_query_string(uri) -> parameter_matcher
+    # Matches a URI without regard to the ordering of parameters in the query string.
     #
-    # Matches a URI without regard to the ordering of parameters in the query string
+    # @param [String] uri URI to match.
+    # @return [QueryStringMatches] parameter matcher.
+    #
+    # @see Expectation#with
+    #
+    # @example Actual URI has equivalent query string.
     #   object = mock()
     #   object.expects(:method_1).with(has_equivalent_query_string('http://example.com/foo?a=1&b=2))
     #   object.method_1('http://example.com/foo?b=2&a=1')
     #   # no error raised
     #
+    # @example Actual URI does not have equivalent query string.
     #   object = mock()
     #   object.expects(:method_1).with(has_equivalent_query_string('http://example.com/foo?a=1&b=2))
     #   object.method_1('http://example.com/foo?a=1&b=3')
@@ -20,23 +26,28 @@ module Mocha
       QueryStringMatches.new(uri)
     end
 
-    class QueryStringMatches < Base # :nodoc:
+    # Parameter matcher which matches URIs with equivalent query strings.
+    class QueryStringMatches < Base
 
+      # @private
       def initialize(uri)
         @uri = URI.parse(uri)
       end
 
+      # @private
       def matches?(available_parameters)
         actual = explode(URI.parse(available_parameters.shift))
         expected = explode(@uri)
         actual == expected
       end
 
+      # @private
       def mocha_inspect
         "has_equivalent_query_string(#{@uri.mocha_inspect})"
       end
 
     private
+      # @private
       def explode(uri)
         query_hash = (uri.query || '').split('&').inject({}){ |h, kv| h.merge(Hash[*kv.split('=')]) }
         URI::Generic::COMPONENT.inject({}){ |h, k| h.merge(k => uri.__send__(k)) }.merge(:query => query_hash)

data/lib/mocha/parameter_matchers/regexp_matches.rb

@@ -1,44 +1,54 @@
 require 'mocha/parameter_matchers/base'
 
 module Mocha
-  
+
   module ParameterMatchers
 
-    # :call-seq: regexp_matches(regular_expression) -> parameter_matcher
+    # Matches any object that matches +regexp+.
+    #
+    # @param [Regexp] regexp regular expression to match.
+    # @return [RegexpMatches] parameter matcher.
+    #
+    # @see Expectation#with
     #
-    # Matches any object that matches +regular_expression+.
+    # @example Actual parameter is matched by specified regular expression.
     #   object = mock()
     #   object.expects(:method_1).with(regexp_matches(/e/))
     #   object.method_1('hello')
     #   # no error raised
     #
+    # @example Actual parameter is not matched by specified regular expression.
     #   object = mock()
     #   object.expects(:method_1).with(regexp_matches(/a/))
     #   object.method_1('hello')
-    #   # error raised, because method_1 was not called with a parameter that matched the 
+    #   # error raised, because method_1 was not called with a parameter that matched the
     #   # regular expression
     def regexp_matches(regexp)
       RegexpMatches.new(regexp)
     end
 
-    class RegexpMatches < Base # :nodoc:
-  
+    # Parameter matcher which matches if specified regular expression matches actual paramter.
+    class RegexpMatches < Base
+
+      # @private
       def initialize(regexp)
         @regexp = regexp
       end
-  
+
+      # @private
       def matches?(available_parameters)
         parameter = available_parameters.shift
         return false unless parameter.respond_to?(:=~)
         parameter =~ @regexp
       end
-  
+
+      # @private
       def mocha_inspect
         "regexp_matches(#{@regexp.mocha_inspect})"
       end
-  
+
     end
-    
+
   end
-  
+
 end

data/lib/mocha/parameter_matchers/responds_with.rb

@@ -5,14 +5,21 @@ module Mocha
 
   module ParameterMatchers
 
-    # :call-seq: responds_with(message, result) -> parameter_matcher
-    #
     # Matches any object that responds to +message+ with +result+. To put it another way, it tests the quack, not the duck.
+    #
+    # @param [Symbol] message method to invoke.
+    # @param [Object] result expected result of sending +message+.
+    # @return [RespondsWith] parameter matcher.
+    #
+    # @see Expectation#with
+    #
+    # @example Actual parameter responds with "FOO" when :upcase is invoked.
     #   object = mock()
     #   object.expects(:method_1).with(responds_with(:upcase, "FOO"))
     #   object.method_1("foo")
     #   # no error raised, because "foo".upcase == "FOO"
     #
+    # @example Actual parameter does not respond with "FOO" when :upcase is invoked.
     #   object = mock()
     #   object.expects(:method_1).with(responds_with(:upcase, "BAR"))
     #   object.method_1("foo")
@@ -21,23 +28,27 @@ module Mocha
       RespondsWith.new(message, result)
     end
 
-    class RespondsWith < Base # :nodoc:
+    # Parameter matcher which matches if actual parameter returns expected result when specified method is invoked.
+    class RespondsWith < Base
 
+      # @private
       def initialize(message, result)
         @message, @result = message, result
       end
 
+      # @private
       def matches?(available_parameters)
         parameter = available_parameters.shift
         parameter.__send__(@message) == @result
       end
 
+      # @private
       def mocha_inspect
         "responds_with(#{@message.mocha_inspect}, #{@result.mocha_inspect})"
       end
-      
+
     end
-    
+
   end
-  
+
 end

data/lib/mocha/parameter_matchers/yaml_equivalent.rb

@@ -5,14 +5,20 @@ module Mocha
 
   module ParameterMatchers
 
-    # :call-seq: yaml_equivalent(object) -> parameter_matcher
-    #
     # Matches any YAML that represents the specified +object+
+    #
+    # @param [Object] object object whose YAML to compare.
+    # @return [YamlEquivalent] parameter matcher.
+    #
+    # @see Expectation#with
+    #
+    # @example Actual parameter is YAML equivalent of specified +object+.
     #   object = mock()
     #   object.expects(:method_1).with(yaml_equivalent(1, 2, 3))
     #   object.method_1("--- \n- 1\n- 2\n- 3\n")
     #   # no error raised
     #
+    # @example Actual parameter is not YAML equivalent of specified +object+.
     #   object = mock()
     #   object.expects(:method_1).with(yaml_equivalent(1, 2, 3))
     #   object.method_1("--- \n- 1\n- 2\n")
@@ -21,23 +27,27 @@ module Mocha
       YamlEquivalent.new(object)
     end
 
-    class YamlEquivalent < Base # :nodoc:
+    # Parameter matcher which matches if actual parameter is YAML equivalent of specified object.
+    class YamlEquivalent < Base
 
+      # @private
       def initialize(object)
         @object = object
       end
 
+      # @private
       def matches?(available_parameters)
         parameter = available_parameters.shift
         @object == YAML.load(parameter)
       end
 
+      # @private
       def mocha_inspect
         "yaml_equivalent(#{@object.mocha_inspect})"
       end
-      
+
     end
-    
+
   end
-  
+
 end

data/lib/mocha/parameters_matcher.rb

@@ -2,13 +2,13 @@ require 'mocha/inspect'
 require 'mocha/parameter_matchers'
 
 module Mocha
-  
+
   class ParametersMatcher
-    
+
     def initialize(expected_parameters = [ParameterMatchers::AnyParameters.new], &matching_block)
       @expected_parameters, @matching_block = expected_parameters, matching_block
     end
-    
+
     def match?(actual_parameters = [])
       if @matching_block
         return @matching_block.call(*actual_parameters)
@@ -16,22 +16,22 @@ module Mocha
         return parameters_match?(actual_parameters)
       end
     end
-    
+
     def parameters_match?(actual_parameters)
       matchers.all? { |matcher| matcher.matches?(actual_parameters) } && (actual_parameters.length == 0)
     end
-    
+
     def mocha_inspect
       signature = matchers.mocha_inspect
       signature = signature.gsub(/^\[|\]$/, '')
       signature = signature.gsub(/^\{|\}$/, '') if matchers.length == 1
       "(#{signature})"
     end
-    
+
     def matchers
       @expected_parameters.map { |parameter| parameter.to_matcher }
     end
-    
+
   end
 
-end
+end

data/lib/mocha/pretty_parameters.rb

@@ -3,26 +3,26 @@ require 'mocha/inspect'
 module Mocha
 
   class PrettyParameters
-  
+
     def initialize(params)
       @params = params
       @params_string = params.mocha_inspect
     end
-  
+
     def pretty
       remove_outer_array_braces!
       remove_outer_hash_braces!
       @params_string
     end
-  
+
     def remove_outer_array_braces!
       @params_string = @params_string.gsub(/^\[|\]$/, '')
     end
-  
+
     def remove_outer_hash_braces!
       @params_string = @params_string.gsub(/^\{|\}$/, '') if @params.length == 1
     end
-  
+
   end
-  
-end
+
+end