mocha 0.10.5 → 0.11.0

data/lib/mocha/parameter_matchers.rb

@@ -1,8 +1,8 @@
 module Mocha
-  
-  # Used as parameters for Expectation#with to restrict the parameter values which will match the expectation. Can be nested.
+
+  # Used as parameters for {Expectation#with} to restrict the parameter values which will match the expectation. Can be nested.
   module ParameterMatchers; end
-  
+
 end
 
 require 'mocha/parameter_matchers/object'

data/lib/mocha/parameter_matchers/all_of.rb

@@ -1,17 +1,23 @@
 require 'mocha/parameter_matchers/base'
 
 module Mocha
-  
+
   module ParameterMatchers
 
-    # :call-seq: all_of(*parameter_matchers) -> parameter_matcher
+    # Matches if all +matchers+ match.
+    #
+    # @param [*Array<Base>] parameter_matchers parameter matchers.
+    # @return [AllOf] parameter matcher.
+    #
+    # @see Expectation#with
     #
-    # Matches if all +parameter_matchers+ match.
+    # @example All parameter matchers match.
     #   object = mock()
     #   object.expects(:method_1).with(all_of(includes(1), includes(3)))
     #   object.method_1([1, 3])
     #   # no error raised
     #
+    # @example One of the parameter matchers does not match.
     #   object = mock()
     #   object.expects(:method_1).with(all_of(includes(1), includes(3)))
     #   object.method_1([1, 2])
@@ -19,24 +25,28 @@ module Mocha
     def all_of(*matchers)
       AllOf.new(*matchers)
     end
-    
-    class AllOf < Base # :nodoc:
-      
+
+    # Parameter matcher which combines a number of other matchers using a logical AND.
+    class AllOf < Base
+
+      # @private
       def initialize(*matchers)
         @matchers = matchers
       end
-    
+
+      # @private
       def matches?(available_parameters)
         parameter = available_parameters.shift
         @matchers.all? { |matcher| matcher.to_matcher.matches?([parameter]) }
       end
-      
+
+      # @private
       def mocha_inspect
         "all_of(#{@matchers.map { |matcher| matcher.mocha_inspect }.join(", ") })"
       end
-      
+
     end
-    
+
   end
-  
-end
+
+end

data/lib/mocha/parameter_matchers/any_of.rb

@@ -1,22 +1,29 @@
 require 'mocha/parameter_matchers/base'
 
 module Mocha
-  
+
   module ParameterMatchers
 
-    # :call-seq: any_of(*parameter_matchers) -> parameter_matcher
+    # Matches if any +matchers+ match.
+    #
+    # @param [*Array<Base>] parameter_matchers parameter matchers.
+    # @return [AnyOf] parameter matcher.
+    #
+    # @see Expectation#with
     #
-    # Matches if any +parameter_matchers+ match.
+    # @example One parameter matcher matches.
     #   object = mock()
     #   object.expects(:method_1).with(any_of(1, 3))
     #   object.method_1(1)
     #   # no error raised
     #
+    # @example The other parameter matcher matches.
     #   object = mock()
     #   object.expects(:method_1).with(any_of(1, 3))
     #   object.method_1(3)
     #   # no error raised
     #
+    # @example Neither parameter matcher matches.
     #   object = mock()
     #   object.expects(:method_1).with(any_of(1, 3))
     #   object.method_1(2)
@@ -24,24 +31,28 @@ module Mocha
     def any_of(*matchers)
       AnyOf.new(*matchers)
     end
-    
-    class AnyOf < Base # :nodoc:
-      
+
+    # Parameter matcher which combines a number of other matchers using a logical OR.
+    class AnyOf < Base
+
+      # @private
       def initialize(*matchers)
         @matchers = matchers
       end
-    
+
+      # @private
       def matches?(available_parameters)
         parameter = available_parameters.shift
         @matchers.any? { |matcher| matcher.to_matcher.matches?([parameter]) }
       end
-      
+
+      # @private
       def mocha_inspect
         "any_of(#{@matchers.map { |matcher| matcher.mocha_inspect }.join(", ") })"
       end
-      
+
     end
-    
+
   end
-  
-end
+
+end

data/lib/mocha/parameter_matchers/any_parameters.rb

@@ -1,12 +1,16 @@
 require 'mocha/parameter_matchers/base'
 
 module Mocha
-  
+
   module ParameterMatchers
 
-    # :call-seq: any_parameters() -> parameter_matcher
+    # Matches any parameters. This is used as the default for a newly built expectation.
+    #
+    # @return [AnyParameters] parameter matcher.
+    #
+    # @see Expectation#with
     #
-    # Matches any parameters.
+    # @example Any parameters will match.
     #   object = mock()
     #   object.expects(:method_1).with(any_parameters)
     #   object.method_1(1, 2, 3, 4)
@@ -20,8 +24,10 @@ module Mocha
       AnyParameters.new
     end
 
-    class AnyParameters < Base # :nodoc:
-      
+    # Parameter matcher which always matches whatever the parameters.
+    class AnyParameters < Base
+
+      # @private
       def matches?(available_parameters)
         while available_parameters.length > 0 do
           available_parameters.shift
@@ -29,12 +35,13 @@ module Mocha
         return true
       end
 
+      # @private
       def mocha_inspect
         "any_parameters"
       end
 
     end
-    
+
   end
-  
-end
+
+end

data/lib/mocha/parameter_matchers/anything.rb

@@ -1,33 +1,42 @@
 require 'mocha/parameter_matchers/base'
 
 module Mocha
-  
+
   module ParameterMatchers
 
-    # :call-seq: anything() -> parameter_matcher
-    #
     # Matches any object.
+    #
+    # @return [Anything] parameter matcher.
+    #
+    # @see Expectation#with
+    #
+    # @example Any object will match.
     #   object = mock()
     #   object.expects(:method_1).with(anything)
     #   object.method_1('foo')
+    #   object.method_1(789)
+    #   object.method_1(:bar)
     #   # no error raised
     def anything
       Anything.new
     end
-    
-    class Anything < Base # :nodoc:
-    
+
+    # Parameter matcher which always matches a single parameter.
+    class Anything < Base
+
+      # @private
       def matches?(available_parameters)
         available_parameters.shift
         return true
       end
-      
+
+      # @private
       def mocha_inspect
         "anything"
       end
-      
+
     end
-    
+
   end
-  
-end
+
+end

data/lib/mocha/parameter_matchers/base.rb

@@ -1,53 +1,61 @@
 module Mocha
-  
+
   module ParameterMatchers
-    
-    class Base 
-      
-      def to_matcher # :nodoc:
+
+    # @abstract Subclass and implement +#matches?+ and +#mocha_inspect+ to define a custom matcher. Also add a suitably named instance method to {ParameterMatchers} to build an instance of the new matcher c.f. {#equals}.
+    class Base
+
+      # @private
+      def to_matcher
         self
       end
-      
-      # :call-seq: &(matcher) -> parameter_matcher
+
+      # A shorthand way of combining two matchers when both must match.
       #
-      # A short hand way of specifying multiple matchers that should
-      # all match.
+      # Returns a new {AllOf} parameter matcher combining two matchers using a logical AND.
       #
-      # Returns a new +AllOf+ parameter matcher combining the
-      # given matcher and the receiver.
+      # This shorthand will not work with an implicit equals match. Instead, an explicit {Equals} matcher should be used.
       #
-      # The following statements are equivalent:
+      # @param [Base] matcher parameter matcher.
+      # @return [AllOf] parameter matcher.
+      #
+      # @see Expectation#with
+      #
+      # @example Alternative ways to combine matchers with a logical AND.
       #   object = mock()
       #   object.expects(:run).with(all_of(has_key(:foo), has_key(:bar)))
       #   object.run(:foo => 'foovalue', :bar => 'barvalue')
       #
-      #   # with the shorthand
+      #   # is exactly equivalent to
+      #
       #   object.expects(:run).with(has_key(:foo) & has_key(:bar))
       #   object.run(:foo => 'foovalue', :bar => 'barvalue)
       def &(matcher)
         AllOf.new(self, matcher)
       end
-      
-      # :call-seq: |(matcher) -> parameter_matcher
+
+      # A shorthand way of combining two matchers when at least one must match.
+      #
+      # Returns a new +AnyOf+ parameter matcher combining two matchers using a logical OR.
       #
-      # A short hand way of specifying multiple matchers, only at least
-      # one of which should pass.
+      # This shorthand will not work with an implicit equals match. Instead, an explicit {Equals} matcher should be used.
       #
-      # Returns a new +AnyOf+ parameter matcher combining the
-      # given matcher and the receiver.
+      # @param [Base] matcher parameter matcher.
+      # @return [AnyOf] parameter matcher.
       #
-      # The following statements are equivalent:
+      # @see Expectation#with
+      #
+      # @example Alternative ways to combine matchers with a logical OR.
       #   object = mock()
       #   object.expects(:run).with(any_of(has_key(:foo), has_key(:bar)))
       #   object.run(:foo => 'foovalue')
       #
-      #   # with the shorthand
+      #   # is exactly equivalent to
+      #
       #   object.expects(:run).with(has_key(:foo) | has_key(:bar))
       #   object.run(:foo => 'foovalue')
       #
-      # This shorthand will not work with an implicit equals match. Instead,
-      # an explicit equals matcher should be used:
-      #
+      # @example Using an explicit {Equals} matcher in combination with {#|}.
       #   object.expects(:run).with(equals(1) | equals(2))
       #   object.run(1) # passes
       #   object.run(2) # passes
@@ -55,9 +63,9 @@ module Mocha
       def |(matcher)
         AnyOf.new(self, matcher)
       end
-      
+
     end
-    
+
   end
-  
+
 end

data/lib/mocha/parameter_matchers/equals.rb

@@ -1,42 +1,53 @@
 require 'mocha/parameter_matchers/base'
 
 module Mocha
-  
+
   module ParameterMatchers
 
-    # :call-seq: equals(value) -> parameter_matcher
+    # Matches any +Object+ equalling +value+.
+    #
+    # @param [Object] value expected value.
+    # @return [Equals] parameter matcher.
+    #
+    # @see Expectation#with
+    # @see Object#==
     #
-    # Matches +Object+ equalling +value+.
+    # @example Actual parameter equals expected parameter.
     #   object = mock()
     #   object.expects(:method_1).with(equals(2))
     #   object.method_1(2)
     #   # no error raised
     #
+    # @example Actual parameter does not equal expected parameter.
     #   object = mock()
     #   object.expects(:method_1).with(equals(2))
     #   object.method_1(3)
-    #   # error raised, because method_1 was not called with Object equalling 3
+    #   # error raised, because method_1 was not called with an +Object+ that equals 3
     def equals(value)
       Equals.new(value)
     end
 
-    class Equals < Base # :nodoc:
-      
+    # Parameter matcher which matches when actual parameter equals expected value.
+    class Equals < Base
+
+      # @private
       def initialize(value)
         @value = value
       end
-      
+
+      # @private
       def matches?(available_parameters)
         parameter = available_parameters.shift
         parameter == @value
       end
-      
+
+      # @private
       def mocha_inspect
         @value.mocha_inspect
       end
-      
+
     end
-    
+
   end
-  
-end
+
+end

data/lib/mocha/parameter_matchers/has_entries.rb

@@ -3,17 +3,23 @@ require 'mocha/parameter_matchers/all_of'
 require 'mocha/parameter_matchers/has_entry'
 
 module Mocha
-  
+
   module ParameterMatchers
 
-    # :call-seq: has_entries(entries) -> parameter_matcher
-    #
     # Matches +Hash+ containing all +entries+.
+    #
+    # @param [Hash] entries expected +Hash+ entries.
+    # @return [HasEntries] parameter matcher.
+    #
+    # @see Expectation#with
+    #
+    # @example Actual parameter contains all expected entries.
     #   object = mock()
     #   object.expects(:method_1).with(has_entries('key_1' => 1, 'key_2' => 2))
     #   object.method_1('key_1' => 1, 'key_2' => 2, 'key_3' => 3)
     #   # no error raised
     #
+    # @example Actual parameter does not contain all expected entries.
     #   object = mock()
     #   object.expects(:method_1).with(has_entries('key_1' => 1, 'key_2' => 2))
     #   object.method_1('key_1' => 1, 'key_2' => 99)
@@ -21,25 +27,29 @@ module Mocha
     def has_entries(entries)
       HasEntries.new(entries)
     end
-    
-    class HasEntries < Base # :nodoc:
-      
+
+    # Parameter matcher which matches when actual parameter contains all expected +Hash+ entries.
+    class HasEntries < Base
+
+      # @private
       def initialize(entries)
         @entries = entries
       end
-      
+
+      # @private
       def matches?(available_parameters)
         parameter = available_parameters.shift
         has_entry_matchers = @entries.map { |key, value| HasEntry.new(key, value) }
         AllOf.new(*has_entry_matchers).matches?([parameter])
       end
-      
+
+      # @private
       def mocha_inspect
         "has_entries(#{@entries.mocha_inspect})"
       end
-      
+
     end
-    
+
   end
-  
-end
+
+end