mocha 0.10.5 → 0.11.0

data/lib/mocha/integration/test_unit/assertion_counter.rb

@@ -1,23 +1,23 @@
 module Mocha
-  
+
   module Integration
-    
+
     module TestUnit
-      
+
       class AssertionCounter
-        
+
         def initialize(test_result)
           @test_result = test_result
         end
-        
+
         def increment
           @test_result.add_assertion
         end
-        
+
       end
-      
+
     end
-    
+
   end
-  
-end
+
+end

data/lib/mocha/integration/test_unit/gem_version_200.rb

@@ -3,11 +3,11 @@ require 'mocha/integration/test_unit/assertion_counter'
 require 'mocha/expectation_error'
 
 module Mocha
-  
+
   module Integration
-    
+
     module TestUnit
-      
+
       module GemVersion200
         def self.included(mod)
           $stderr.puts "Monkey patching Test::Unit gem v2.0.0" if $mocha_options['debug']
@@ -44,9 +44,9 @@ module Mocha
           end
         end
       end
-      
+
     end
-    
+
   end
-  
+
 end

data/lib/mocha/integration/test_unit/gem_version_201_to_202.rb

@@ -3,11 +3,11 @@ require 'mocha/integration/test_unit/assertion_counter'
 require 'mocha/expectation_error'
 
 module Mocha
-  
+
   module Integration
-    
+
     module TestUnit
-      
+
       module GemVersion201To202
         def self.included(mod)
           $stderr.puts "Monkey patching Test::Unit gem >= v2.0.1 and <= v2.0.2" if $mocha_options['debug']
@@ -44,9 +44,9 @@ module Mocha
           end
         end
       end
-      
+
     end
-    
+
   end
-  
+
 end

data/lib/mocha/integration/test_unit/ruby_version_185_and_below.rb

@@ -3,11 +3,11 @@ require 'mocha/integration/test_unit/assertion_counter'
 require 'mocha/expectation_error'
 
 module Mocha
-  
+
   module Integration
-    
+
     module TestUnit
-      
+
       module RubyVersion185AndBelow
         def self.included(mod)
           $stderr.puts "Monkey patching Test::Unit for Ruby <= v1.8.5" if $mocha_options['debug']
@@ -43,9 +43,9 @@ module Mocha
           yield(Test::Unit::TestCase::FINISHED, name)
         end
       end
-      
+
     end
-    
+
   end
-  
+
 end

data/lib/mocha/integration/test_unit/ruby_version_186_and_above.rb

@@ -3,11 +3,11 @@ require 'mocha/integration/test_unit/assertion_counter'
 require 'mocha/expectation_error'
 
 module Mocha
-  
+
   module Integration
-    
+
     module TestUnit
-      
+
       module RubyVersion186AndAbove
         def self.included(mod)
           $stderr.puts "Monkey patching Test::Unit for Ruby >= v1.8.6" if $mocha_options['debug']
@@ -45,9 +45,9 @@ module Mocha
           yield(Test::Unit::TestCase::FINISHED, name)
         end
       end
-      
+
     end
-    
+
   end
-  
+
 end

data/lib/mocha/is_a.rb

@@ -5,5 +5,5 @@ class Object
   alias_method :__is_a__, :is_a?
 
   # :startdoc:
-  
+
 end

data/lib/mocha/logger.rb

@@ -1,15 +1,15 @@
 module Mocha
-  
+
   class Logger
-    
+
     def initialize(io)
       @io = io
     end
-    
+
     def warn(message)
       @io.puts "WARNING: #{message}"
     end
-    
+
   end
-  
-end
+
+end

data/lib/mocha/method_matcher.rb

@@ -1,21 +1,21 @@
 module Mocha
-  
+
   class MethodMatcher
-    
+
     attr_reader :expected_method_name
-    
+
     def initialize(expected_method_name)
       @expected_method_name = expected_method_name
     end
-    
+
     def match?(actual_method_name)
       @expected_method_name == actual_method_name
     end
-    
+
     def mocha_inspect
       "#{@expected_method_name}"
     end
-    
+
   end
 
-end
+end

data/lib/mocha/mock.rb

@@ -7,37 +7,47 @@ require 'mocha/parameters_matcher'
 require 'mocha/unexpected_invocation'
 require 'mocha/argument_iterator'
 
-module Mocha # :nodoc:
+module Mocha
 
   # Traditional mock object.
   #
-  # Methods return an Expectation which can be further modified by methods on Expectation.
+  # All methods return an {Expectation} which can be further modified by methods on {Expectation}.
   class Mock
 
-    # :call-seq: expects(method_name) -> expectation
-    #            expects(method_names_vs_return_values) -> last expectation
+    # Adds an expectation that the specified method must be called exactly once with any parameters.
     #
-    # Adds an expectation that a method identified by +method_name+ Symbol/String must be called exactly once with any parameters.
-    # Returns the new expectation which can be further modified by methods on Expectation.
-    #   object = mock()
-    #   object.expects(:method1)
-    #   object.method1
-    #   # no error raised
+    # @param [Symbol,String] method_name name of expected method
+    # @param [Hash] expected_methods_vs_return_values expected method name symbols as keys and corresponding return values as values - these expectations are setup as if {#expects} were called multiple times.
     #
+    # @overload def expects(method_name)
+    # @overload def expects(expected_methods_vs_return_values)
+    # @return [Expectation] last-built expectation which can be further modified by methods on {Expectation}.
+    #
+    # @example Expected method invoked once so no error raised
     #   object = mock()
-    #   object.expects(:method1)
-    #   # error raised, because method1 not called exactly once
-    # If +method_names_vs_return_values+ is a +Hash+, an expectation will be set up for each entry using the key as +method_name+ and value as +return_value+.
+    #   object.expects(:expected_method)
+    #   object.expected_method
+    #
+    # @example Expected method not invoked so error raised
     #   object = mock()
-    #   object.expects(:method1 => :result1, :method2 => :result2)
+    #   object.expects(:expected_method)
+    #   # error raised when test completes, because expected_method not called exactly once
     #
-    #   # exactly equivalent to
+    # @example Expected method invoked twice so error raised
+    #   object = mock()
+    #   object.expects(:expected_method)
+    #   object.expected_method
+    #   object.expected_method # => error raised when expected method invoked second time
     #
+    # @example Setup multiple expectations using +expected_methods_vs_return_values+.
     #   object = mock()
-    #   object.expects(:method1).returns(:result1)
-    #   object.expects(:method2).returns(:result2)
+    #   object.expects(:expected_method_one => :result_one, :expected_method_two => :result_two)
+    #
+    #   # is exactly equivalent to
     #
-    # Aliased by <tt>\_\_expects\_\_</tt>
+    #   object = mock()
+    #   object.expects(:expected_method_one).returns(:result_one)
+    #   object.expects(:expected_method_two).returns(:result_two)
     def expects(method_name_or_hash, backtrace = nil)
       iterator = ArgumentIterator.new(method_name_or_hash)
       iterator.each { |*args|
@@ -49,27 +59,31 @@ module Mocha # :nodoc:
       }
     end
 
-    # :call-seq: stubs(method_name) -> expectation
-    #            stubs(method_names_vs_return_values) -> last expectation
+    # Adds an expectation that the specified method may be called any number of times with any parameters.
     #
-    # Adds an expectation that a method identified by +method_name+ Symbol/String may be called any number of times with any parameters.
-    # Returns the new expectation which can be further modified by methods on Expectation.
+    # @param [Symbol,String] method_name name of stubbed method
+    # @param [Hash] stubbed_methods_vs_return_values stubbed method name symbols as keys and corresponding return values as values - these stubbed methods are setup as if {#stubs} were called multiple times.
+    #
+    # @overload def stubs(method_name)
+    # @overload def stubs(stubbed_methods_vs_return_values)
+    # @return [Expectation] last-built expectation which can be further modified by methods on {Expectation}.
+    #
+    # @example No error raised however many times stubbed method is invoked
     #   object = mock()
-    #   object.stubs(:method1)
-    #   object.method1
-    #   object.method1
+    #   object.stubs(:stubbed_method)
+    #   object.stubbed_method
+    #   object.stubbed_method
     #   # no error raised
-    # If +method_names_vs_return_values+ is a +Hash+, an expectation will be set up for each entry using the key as +method_name+ and value as +return_value+.
+    #
+    # @example Setup multiple expectations using +stubbed_methods_vs_return_values+.
     #   object = mock()
-    #   object.stubs(:method1 => :result1, :method2 => :result2)
+    #   object.stubs(:stubbed_method_one => :result_one, :stubbed_method_two => :result_two)
     #
-    #   # exactly equivalent to
+    #   # is exactly equivalent to
     #
     #   object = mock()
-    #   object.stubs(:method1).returns(:result1)
-    #   object.stubs(:method2).returns(:result2)
-    #
-    # Aliased by <tt>\_\_stubs\_\_</tt>
+    #   object.stubs(:stubbed_method_one).returns(:result_one)
+    #   object.stubs(:stubbed_method_two).returns(:result_two)
     def stubs(method_name_or_hash, backtrace = nil)
       iterator = ArgumentIterator.new(method_name_or_hash)
       iterator.each { |*args|
@@ -82,22 +96,30 @@ module Mocha # :nodoc:
       }
     end
 
+    # Removes the specified stubbed method (added by calls to {#expects} or {#stubs}) and all expectations associated with it.
+    #
+    # @param [Symbol] method_name name of method to unstub.
+    #
+    # @example Invoking an unstubbed method causes error to be raised
+    #   object = mock('mock') do
+    #   object.stubs(:stubbed_method).returns(:result_one)
+    #   object.stubbed_method # => :result_one
+    #   object.unstub(:stubbed_method)
+    #   object.stubbed_method # => unexpected invocation: #<Mock:mock>.stubbed_method()
     def unstub(method_name)
       @expectations.remove_all_matching_method(method_name)
     end
 
-    # :call-seq: responds_like(responder) -> mock
+    # Constrains the {Mock} instance so that it can only expect or stub methods to which +responder+ responds. The constraint is only applied at method invocation time.
     #
-    # Constrains the +mock+ so that it can only expect or stub methods to which +responder+ responds. The constraint is only applied at method invocation time.
+    # A +NoMethodError+ will be raised if the +responder+ does not +#respond_to?+ a method invocation (even if the method has been expected or stubbed).
     #
-    # A +NoMethodError+ will be raised if the +responder+ does not <tt>respond_to?</tt> a method invocation (even if the method has been expected or stubbed).
+    # The {Mock} instance will delegate its +#respond_to?+ method to the +responder+.
     #
-    # The +mock+ will delegate its <tt>respond_to?</tt> method to the +responder+.
-    #   class Sheep
-    #     def chew(grass); end
-    #     def self.number_of_legs; end
-    #   end
+    # @param [Object, #respond_to?] responder an object used to determine whether {Mock} instance should +#respond_to?+ to an invocation.
+    # @return [Mock] the same {Mock} instance, thereby allowing invocations of other {Mock} methods to be chained.
     #
+    # @example Normal mocking
     #   sheep = mock('sheep')
     #   sheep.expects(:chew)
     #   sheep.expects(:foo)
@@ -107,6 +129,11 @@ module Mocha # :nodoc:
     #   sheep.foo
     #   # no error raised
     #
+    # @example Using {#responds_like} with an instance method
+    #   class Sheep
+    #     def chew(grass); end
+    #   end
+    #
     #   sheep = mock('sheep')
     #   sheep.responds_like(Sheep.new)
     #   sheep.expects(:chew)
@@ -116,6 +143,11 @@ module Mocha # :nodoc:
     #   sheep.chew
     #   sheep.foo # => raises NoMethodError exception
     #
+    # @example Using {#responds_like} with a class method
+    #   class Sheep
+    #     def self.number_of_legs; end
+    #   end
+    #
     #   sheep_class = mock('sheep_class')
     #   sheep_class.responds_like(Sheep)
     #   sheep_class.stubs(:number_of_legs).returns(4)
@@ -124,15 +156,12 @@ module Mocha # :nodoc:
     #   sheep_class.respond_to?(:foo) # => false
     #   assert_equal 4, sheep_class.number_of_legs
     #   sheep_class.foo # => raises NoMethodError exception
-    #
-    # Aliased by +quacks_like+
-    def responds_like(object)
-      @responder = object
+    def responds_like(responder)
+      @responder = responder
       self
     end
 
-    # :stopdoc:
-
+    # @private
     def initialize(mockery, name = nil, &block)
       @mockery = mockery
       @name = name || DefaultName.new(self)
@@ -142,6 +171,7 @@ module Mocha # :nodoc:
       instance_eval(&block) if block
     end
 
+    # @private
     attr_reader :everything_stubbed
 
     alias_method :__expects__, :expects
@@ -150,14 +180,17 @@ module Mocha # :nodoc:
 
     alias_method :quacks_like, :responds_like
 
+    # @private
     def __expectations__
       @expectations
     end
 
+    # @private
     def stub_everything
       @everything_stubbed = true
     end
 
+    # @private
     def method_missing(symbol, *arguments, &block)
       if @responder and not @responder.respond_to?(symbol)
         raise NoMethodError, "undefined method `#{symbol}' for #{self.mocha_inspect} which responds like #{@responder.mocha_inspect}"
@@ -174,6 +207,7 @@ module Mocha # :nodoc:
       end
     end
 
+    # @private
     def respond_to?(symbol, include_private = false)
       if @responder then
         if @responder.method(:respond_to?).arity > 1
@@ -186,28 +220,31 @@ module Mocha # :nodoc:
       end
     end
 
+    # @private
     def __verified__?(assertion_counter = nil)
       @expectations.verified?(assertion_counter)
     end
 
+    # @private
     def mocha_inspect
       @name.mocha_inspect
     end
 
+    # @private
     def inspect
       mocha_inspect
     end
 
+    # @private
     def ensure_method_not_already_defined(method_name)
       self.__metaclass__.send(:undef_method, method_name) if self.__metaclass__.method_defined?(method_name)
     end
 
+    # @private
     def any_expectations?
       @expectations.any?
     end
 
-    # :startdoc:
-
   end
 
 end