mocha 0.10.5 → 0.11.0

data/lib/mocha/backtrace_filter.rb

@@ -1,7 +1,7 @@
 module Mocha
 
   class BacktraceFilter
-  
+
     LIB_DIRECTORY = File.expand_path(File.join(File.dirname(__FILE__), "..")) + File::SEPARATOR
 
     def initialize(lib_directory = LIB_DIRECTORY)

data/lib/mocha/cardinality.rb

@@ -1,60 +1,60 @@
 module Mocha
 
   class Cardinality
-    
+
     INFINITY = 1 / 0.0
-    
+
     class << self
-      
+
       def exactly(count)
         new(count, count)
       end
-      
+
       def at_least(count)
         new(count, INFINITY)
       end
-      
+
       def at_most(count)
         new(0, count)
       end
-      
+
       def times(range_or_count)
         case range_or_count
           when Range then new(range_or_count.first, range_or_count.last)
           else new(range_or_count, range_or_count)
         end
       end
-      
+
     end
-    
+
     def initialize(required, maximum)
       @required, @maximum = required, maximum
     end
-    
+
     def invocations_allowed?(invocation_count)
       invocation_count < maximum
     end
-    
+
     def satisfied?(invocations_so_far)
       invocations_so_far >= required
     end
-    
+
     def needs_verifying?
       !allowed_any_number_of_times?
     end
-    
+
     def verified?(invocation_count)
       (invocation_count >= required) && (invocation_count <= maximum)
     end
-    
+
     def allowed_any_number_of_times?
       required == 0 && infinite?(maximum)
     end
-    
+
     def used?(invocation_count)
       (invocation_count > 0) || (maximum == 0)
     end
-    
+
     def mocha_inspect
       if allowed_any_number_of_times?
         "allowed any number of times"
@@ -72,11 +72,11 @@ module Mocha
         end
       end
     end
-    
+
     protected
-    
+
     attr_reader :required, :maximum
-    
+
     def times(number)
       case number
         when 0 then "no times"
@@ -85,11 +85,11 @@ module Mocha
         else "#{number} times"
       end
     end
-    
+
     def infinite?(number)
       number.respond_to?(:infinite?) && number.infinite?
     end
-    
+
   end
-  
+
 end

data/lib/mocha/central.rb

@@ -1,27 +1,27 @@
 module Mocha
-  
+
   class Central
-  
+
     attr_accessor :stubba_methods
-  
+
     def initialize
       self.stubba_methods = []
     end
-   
+
     def stub(method)
       unless stubba_methods.detect { |m| m.matches?(method) }
-        method.stub 
+        method.stub
         stubba_methods.push(method)
       end
     end
-    
+
     def unstub(method)
       if existing = stubba_methods.detect { |m| m.matches?(method) }
         existing.unstub
         stubba_methods.delete(existing)
       end
     end
-    
+
     def unstub_all
       while stubba_methods.any? do
         unstub(stubba_methods.first)
@@ -30,4 +30,4 @@ module Mocha
 
   end
 
-end
+end

data/lib/mocha/change_state_side_effect.rb

@@ -1,19 +1,19 @@
 module Mocha
 
   class ChangeStateSideEffect
-  
+
     def initialize(state)
       @state = state
     end
-  
+
     def perform
       @state.activate
     end
-  
+
     def mocha_inspect
       "then #{@state.mocha_inspect}"
     end
-  
+
   end
 
-end
+end

data/lib/mocha/class_method.rb

@@ -7,7 +7,7 @@ module Mocha
     attr_reader :stubbee, :method
 
     def initialize(stubbee, method)
-      @stubbee = stubbee
+      @stubbee, @original_method = stubbee, nil
       @method = RUBY_VERSION < '1.9' ? method.to_s : method.to_sym
     end
 
@@ -36,7 +36,16 @@ module Mocha
     def hide_original_method
       if method_exists?(method)
         begin
-          stubbee.__metaclass__.send(:alias_method, hidden_method, method)
+          @original_method = stubbee.method(method)
+          if @original_method && @original_method.owner == stubbee.__metaclass__
+            @original_visibility = :public
+            if stubbee.__metaclass__.protected_instance_methods.include?(method)
+              @original_visibility = :protected
+            elsif stubbee.__metaclass__.private_instance_methods.include?(method)
+              @original_visibility = :private
+            end
+            stubbee.__metaclass__.send(:remove_method, method)
+          end
         rescue NameError
           # deal with nasties like ActiveRecord::Associations::AssociationProxy
         end
@@ -56,24 +65,10 @@ module Mocha
     end
 
     def restore_original_method
-      if method_exists?(hidden_method)
-        begin
-          stubbee.__metaclass__.send(:alias_method, method, hidden_method)
-          stubbee.__metaclass__.send(:remove_method, hidden_method)
-        rescue NameError
-          # deal with nasties like ActiveRecord::Associations::AssociationProxy
-        end
-      end
-    end
-
-    def hidden_method
-      if RUBY_VERSION < '1.9'
-        method_name = method.to_s.gsub(/\W/) { |s| "_substituted_character_#{s[0]}_" }
-      else
-        method_name = method.to_s.gsub(/\W/) { |s| "_substituted_character_#{s.ord}_" }
+      if @original_method && @original_method.owner == stubbee.__metaclass__
+        stubbee.__metaclass__.send(:define_method, method, @original_method.to_proc)
+        stubbee.__metaclass__.send(@original_visibility, method)
       end
-      hidden_method = "__stubba__#{method_name}__stubba__"
-      RUBY_VERSION < '1.9' ? hidden_method.to_s : hidden_method.to_sym
     end
 
     def matches?(other)

data/lib/mocha/configuration.rb

@@ -1,62 +1,71 @@
-module Mocha # :nodoc:
-  
-  # Configuration settings
+module Mocha
+
+  # Configuration settings.
   class Configuration
-    
-    DEFAULTS = { :stubbing_method_unnecessarily => :allow, :stubbing_method_on_non_mock_object => :allow, :stubbing_non_existent_method => :allow, :stubbing_non_public_method => :allow }
-    
+
+    DEFAULTS = {
+      :stubbing_method_unnecessarily => :allow,
+      :stubbing_method_on_non_mock_object => :allow,
+      :stubbing_non_existent_method => :allow,
+      :stubbing_non_public_method => :allow,
+      :stubbing_method_on_nil => :prevent,
+    }
+
     class << self
-    
-      # :call-seq: allow(action, &block)
+
+      # Allow the specified +action+.
       #
-      # Allow the specified <tt>action</tt> (as a symbol).
-      # The <tt>actions</tt> currently available are <tt>:stubbing_method_unnecessarily, :stubbing_method_on_non_mock_object, :stubbing_non_existent_method, :stubbing_non_public_method</tt>.
-      # If given a block, the configuration for the action will only be changed for the duration of the block, and will then be restored to the previous value.
+      # @param [Symbol] action one of +:stubbing_method_unnecessarily+, +:stubbing_method_on_non_mock_object+, +:stubbing_non_existent_method+, +:stubbing_non_public_method+, +:stubbing_method_on_nil+.
+      # @yield optional block during which the configuration change will be changed before being returned to its original value at the end of the block.
       def allow(action, &block)
         change_config action, :allow, &block
       end
-    
-      def allow?(action) # :nodoc:
+
+      # @private
+      def allow?(action)
         configuration[action] == :allow
       end
-    
-      # :call-seq: warn_when(action, &block)
+
+      # Warn if the specified +action+ is attempted.
       #
-      # Warn if the specified <tt>action</tt> (as a symbol) is attempted.
-      # The <tt>actions</tt> currently available are <tt>:stubbing_method_unnecessarily, :stubbing_method_on_non_mock_object, :stubbing_non_existent_method, :stubbing_non_public_method</tt>.
-      # If given a block, the configuration for the action will only be changed for the duration of the block, and will then be restored to the previous value.
+      # @param [Symbol] action one of +:stubbing_method_unnecessarily+, +:stubbing_method_on_non_mock_object+, +:stubbing_non_existent_method+, +:stubbing_non_public_method+, +:stubbing_method_on_nil+.
+      # @yield optional block during which the configuration change will be changed before being returned to its original value at the end of the block.
       def warn_when(action, &block)
         change_config action, :warn, &block
       end
-    
-      def warn_when?(action) # :nodoc:
+
+      # @private
+      def warn_when?(action)
         configuration[action] == :warn
       end
-    
-      # :call-seq: prevent(action, &block)
+
+      # Raise a {StubbingError} if if the specified +action+ is attempted.
       #
-      # Raise a StubbingError if the specified <tt>action</tt> (as a symbol) is attempted.
-      # The <tt>actions</tt> currently available are <tt>:stubbing_method_unnecessarily, :stubbing_method_on_non_mock_object, :stubbing_non_existent_method, :stubbing_non_public_method</tt>.
-      # If given a block, the configuration for the action will only be changed for the duration of the block, and will then be restored to the previous value.
+      # @param [Symbol] action one of +:stubbing_method_unnecessarily+, +:stubbing_method_on_non_mock_object+, +:stubbing_non_existent_method+, +:stubbing_non_public_method+, +:stubbing_method_on_nil+.
+      # @yield optional block during which the configuration change will be changed before being returned to its original value at the end of the block.
       def prevent(action, &block)
         change_config action, :prevent, &block
       end
-    
-      def prevent?(action) # :nodoc:
+
+      # @private
+      def prevent?(action)
         configuration[action] == :prevent
       end
-    
-      def reset_configuration # :nodoc:
+
+      # @private
+      def reset_configuration
         @configuration = nil
       end
-    
+
       private
-    
-      def configuration # :nodoc:
+
+      # @private
+      def configuration
         @configuration ||= DEFAULTS.dup
       end
 
-      def change_config(action, new_value, &block) # :nodoc:
+      # @private
+      def change_config(action, new_value, &block)
         if block_given?
           temporarily_change_config action, new_value, &block
         else
@@ -64,16 +73,17 @@ module Mocha # :nodoc:
         end
       end
 
-      def temporarily_change_config(action, new_value, &block) # :nodoc:
+      # @private
+      def temporarily_change_config(action, new_value, &block)
         original_value = configuration[action]
         configuration[action] = new_value
         yield
       ensure
         configuration[action] = original_value
       end
-    
+
     end
-    
+
   end
-  
+
 end

data/lib/mocha/deprecation.rb

@@ -1,11 +1,11 @@
 module Mocha
-  
+
   class Deprecation
-    
+
     class << self
-      
+
       attr_accessor :mode, :messages
-      
+
       def warning(message)
         @messages << message
         $stderr.puts "Mocha deprecation warning: #{message}" unless mode == :disabled
@@ -13,10 +13,10 @@ module Mocha
       end
 
     end
-  
+
     self.mode = :enabled
     self.messages = []
-    
+
   end
-   
-end
+
+end

data/lib/mocha/exception_raiser.rb

@@ -1,17 +1,17 @@
-module Mocha # :nodoc:
-  
-  class ExceptionRaiser # :nodoc:
-    
+module Mocha
+
+  class ExceptionRaiser
+
     def initialize(exception, message)
       @exception, @message = exception, message
     end
-    
+
     def evaluate
       raise @exception, @exception.to_s if @exception.is_a?(Module) && @exception.ancestors.include?(Interrupt)
       raise @exception, @message if @message
       raise @exception
     end
-    
+
   end
-  
+
 end

data/lib/mocha/expectation.rb

@@ -10,16 +10,17 @@ require 'mocha/in_state_ordering_constraint'
 require 'mocha/change_state_side_effect'
 require 'mocha/cardinality'
 
-module Mocha # :nodoc:
+module Mocha
 
-  # Methods on expectations returned from Mock#expects, Mock#stubs, Object#expects and Object#stubs.
+  # Methods on expectations returned from {Mock#expects}, {Mock#stubs}, {ObjectMethods#expects} and {ObjectMethods#stubs}.
   class Expectation
 
-    # :call-seq: times(range) -> expectation
-    #
     # Modifies expectation so that the number of calls to the expected method must be within a specific +range+.
     #
-    # +range+ can be specified as an exact integer or as a range of integers
+    # @param [Range,Integer] range specifies the allowable range in the number of expected invocations.
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
+    #
+    # @example Specifying a specific number of expected invocations.
     #   object = mock()
     #   object.expects(:expected_method).times(3)
     #   3.times { object.expected_method }
@@ -30,6 +31,7 @@ module Mocha # :nodoc:
     #   2.times { object.expected_method }
     #   # => verify fails
     #
+    # @example Specifying a range in the number of expected invocations.
     #   object = mock()
     #   object.expects(:expected_method).times(2..4)
     #   3.times { object.expected_method }
@@ -44,9 +46,11 @@ module Mocha # :nodoc:
       self
     end
 
-    # :call-seq: twice() -> expectation
-    #
     # Modifies expectation so that the expected method must be called exactly twice.
+    #
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
+    #
+    # @example Expected method must be invoked exactly twice.
     #   object = mock()
     #   object.expects(:expected_method).twice
     #   object.expected_method
@@ -57,8 +61,7 @@ module Mocha # :nodoc:
     #   object.expects(:expected_method).twice
     #   object.expected_method
     #   object.expected_method
-    #   object.expected_method
-    #   # => verify fails
+    #   object.expected_method # => unexpected invocation
     #
     #   object = mock()
     #   object.expects(:expected_method).twice
@@ -69,10 +72,13 @@ module Mocha # :nodoc:
       self
     end
 
-    # :call-seq: once() -> expectation
-    #
     # Modifies expectation so that the expected method must be called exactly once.
+    #
     # Note that this is the default behaviour for an expectation, but you may wish to use it for clarity/emphasis.
+    #
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
+    #
+    # @example Expected method must be invoked exactly once.
     #   object = mock()
     #   object.expects(:expected_method).once
     #   object.expected_method
@@ -81,8 +87,7 @@ module Mocha # :nodoc:
     #   object = mock()
     #   object.expects(:expected_method).once
     #   object.expected_method
-    #   object.expected_method
-    #   # => verify fails
+    #   object.expected_method # => unexpected invocation
     #
     #   object = mock()
     #   object.expects(:expected_method).once
@@ -92,13 +97,14 @@ module Mocha # :nodoc:
       self
     end
 
-    # :call-seq: never() -> expectation
-    #
     # Modifies expectation so that the expected method must never be called.
+    #
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
+    #
+    # @example Expected method must never be called.
     #   object = mock()
     #   object.expects(:expected_method).never
-    #   object.expected_method
-    #   # => verify fails
+    #   object.expected_method # => unexpected invocation
     #
     #   object = mock()
     #   object.expects(:expected_method).never
@@ -108,9 +114,12 @@ module Mocha # :nodoc:
       self
     end
 
-    # :call-seq: at_least(minimum_number_of_times) -> expectation
-    #
     # Modifies expectation so that the expected method must be called at least a +minimum_number_of_times+.
+    #
+    # @param [Integer] minimum_number_of_times minimum number of expected invocations.
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
+    #
+    # @example Expected method must be called at least twice.
     #   object = mock()
     #   object.expects(:expected_method).at_least(2)
     #   3.times { object.expected_method }
@@ -125,9 +134,11 @@ module Mocha # :nodoc:
       self
     end
 
-    # :call-seq: at_least_once() -> expectation
-    #
     # Modifies expectation so that the expected method must be called at least once.
+    #
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
+    #
+    # @example Expected method must be called at least once.
     #   object = mock()
     #   object.expects(:expected_method).at_least_once
     #   object.expected_method
@@ -141,9 +152,12 @@ module Mocha # :nodoc:
       self
     end
 
-    # :call-seq: at_most(maximum_number_of_times) -> expectation
-    #
     # Modifies expectation so that the expected method must be called at most a +maximum_number_of_times+.
+    #
+    # @param [Integer] maximum_number_of_times maximum number of expected invocations.
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
+    #
+    # @example Expected method must be called at most twice.
     #   object = mock()
     #   object.expects(:expected_method).at_most(2)
     #   2.times { object.expected_method }
@@ -151,16 +165,17 @@ module Mocha # :nodoc:
     #
     #   object = mock()
     #   object.expects(:expected_method).at_most(2)
-    #   3.times { object.expected_method }
-    #   # => verify fails
+    #   3.times { object.expected_method } # => unexpected invocation
     def at_most(maximum_number_of_times)
       @cardinality = Cardinality.at_most(maximum_number_of_times)
       self
     end
 
-    # :call-seq: at_most_once() -> expectation
-    #
     # Modifies expectation so that the expected method must be called at most once.
+    #
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
+    #
+    # @example Expected method must be called at most once.
     #   object = mock()
     #   object.expects(:expected_method).at_most_once
     #   object.expected_method
@@ -168,16 +183,23 @@ module Mocha # :nodoc:
     #
     #   object = mock()
     #   object.expects(:expected_method).at_most_once
-    #   2.times { object.expected_method }
-    #   # => verify fails
+    #   2.times { object.expected_method } # => unexpected invocation
     def at_most_once()
       at_most(1)
       self
     end
 
-    # :call-seq: with(*expected_parameters, &matching_block) -> expectation
-    #
     # Modifies expectation so that the expected method must be called with +expected_parameters+.
+    #
+    # May be used with parameter matchers in {ParameterMatchers}.
+    #
+    # @param [*Array] expected_parameters parameters expected.
+    # @yield optional block specifying custom matching.
+    # @yieldparam [*Array] actual_parameters parameters with which expected method was invoked.
+    # @yieldreturn [Boolean] +true+ if +actual_parameters+ are acceptable.
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
+    #
+    # @example Expected method must be called with expected parameters.
     #   object = mock()
     #   object.expects(:expected_method).with(:param1, :param2)
     #   object.expected_method(:param1, :param2)
@@ -187,10 +209,8 @@ module Mocha # :nodoc:
     #   object.expects(:expected_method).with(:param1, :param2)
     #   object.expected_method(:param3)
     #   # => verify fails
-    # May be used with parameter matchers in Mocha::ParameterMatchers.
     #
-    # If a +matching_block+ is given, the block is called with the parameters passed to the expected method.
-    # The expectation is matched if the block evaluates to +true+.
+    # @example Expected method must be called with a value divisible by 4.
     #   object = mock()
     #   object.expects(:expected_method).with() { |value| value % 4 == 0 }
     #   object.expected_method(16)
@@ -205,15 +225,22 @@ module Mocha # :nodoc:
       self
     end
 
-    # :call-seq: yields(*parameters) -> expectation
-    #
     # Modifies expectation so that when the expected method is called, it yields with the specified +parameters+.
+    #
+    # May be called multiple times on the same expectation for consecutive invocations.
+    #
+    # @param [*Array] parameters parameters to be yielded.
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
+    # @see #then
+    #
+    # @example Yield parameters when expected method is invoked.
     #   object = mock()
     #   object.expects(:expected_method).yields('result')
     #   yielded_value = nil
     #   object.expected_method { |value| yielded_value = value }
     #   yielded_value # => 'result'
-    # May be called multiple times on the same expectation for consecutive invocations. Also see Expectation#then.
+    #
+    # @example Yield different parameters on different invocations of the expected method.
     #   object = mock()
     #   object.stubs(:expected_method).yields(1).then.yields(2)
     #   yielded_values_from_first_invocation = []
@@ -227,18 +254,20 @@ module Mocha # :nodoc:
       self
     end
 
-    # :call-seq: multiple_yields(*parameter_groups) -> expectation
-    #
     # Modifies expectation so that when the expected method is called, it yields multiple times per invocation with the specified +parameter_groups+.
     #
-    # Note that each +parameter_group+ should be an Array representing the parameters to be passed to the block for a single yield. In the following example when the expected_method is called, the stub will invoke the block twice, the first time it passes 'result_1', 'result_2' as the parameters, and the second time it passes 'result_3' as the parameters.
+    # @param [*Array<Array>] parameter_groups each element of +parameter_groups+ should iself be an +Array+ representing the parameters to be passed to the block for a single yield.
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
+    # @see #then
     #
+    # @example When the +expected_method+ is called, the stub will invoke the block twice, the first time it passes +'result_1'+, +'result_2'+ as the parameters, and the second time it passes 'result_3' as the parameters.
     #   object = mock()
     #   object.expects(:expected_method).multiple_yields(['result_1', 'result_2'], ['result_3'])
     #   yielded_values = []
     #   object.expected_method { |*values| yielded_values << values }
     #   yielded_values # => [['result_1', 'result_2'], ['result_3]]
-    # May be called multiple times on the same expectation for consecutive invocations. Also see Expectation#then.
+    #
+    # @example Yield different groups of parameters on different invocations of the expected method.
     #   object = mock()
     #   object.stubs(:expected_method).multiple_yields([1, 2], [3]).then.multiple_yields([4], [5, 6])
     #   yielded_values_from_first_invocation = []
@@ -252,32 +281,43 @@ module Mocha # :nodoc:
       self
     end
 
-    # :call-seq: returns(value) -> expectation
-    #            returns(*values) -> expectation
-    #
     # Modifies expectation so that when the expected method is called, it returns the specified +value+.
+    #
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
+    # @see #then
+    #
+    # @overload def returns(value)
+    #   @param [Object] value value to return on invocation of expected method.
+    # @overload def returns(*values)
+    #   @param [*Array] values values to return on consecutive invocations of expected method.
+    #
+    # @example Return the same value on every invocation.
     #   object = mock()
     #   object.stubs(:stubbed_method).returns('result')
     #   object.stubbed_method # => 'result'
     #   object.stubbed_method # => 'result'
-    # If multiple +values+ are given, these are returned in turn on consecutive calls to the method.
+    #
+    # @example Return a different value on consecutive invocations.
     #   object = mock()
     #   object.stubs(:stubbed_method).returns(1, 2)
     #   object.stubbed_method # => 1
     #   object.stubbed_method # => 2
-    # May be called multiple times on the same expectation. Also see Expectation#then.
+    #
+    # @example Alternative way to return a different value on consecutive invocations.
     #   object = mock()
     #   object.stubs(:expected_method).returns(1, 2).then.returns(3)
     #   object.expected_method # => 1
     #   object.expected_method # => 2
     #   object.expected_method # => 3
-    # May be called in conjunction with Expectation#raises on the same expectation.
+    #
+    # @example May be called in conjunction with {#raises} on the same expectation.
     #   object = mock()
     #   object.stubs(:expected_method).returns(1, 2).then.raises(Exception)
     #   object.expected_method # => 1
     #   object.expected_method # => 2
     #   object.expected_method # => raises exception of class Exception1
-    # Note that in Ruby a method returning multiple values is exactly equivalent to a method returning an Array of those values.
+    #
+    # @example Note that in Ruby a method returning multiple values is exactly equivalent to a method returning an +Array+ of those values.
     #   object = mock()
     #   object.stubs(:expected_method).returns([1, 2])
     #   x, y = object.expected_method
@@ -288,22 +328,36 @@ module Mocha # :nodoc:
       self
     end
 
-    # :call-seq: raises(exception = RuntimeError, message = nil) -> expectation
+    # Modifies expectation so that when the expected method is called, it raises the specified +exception+ with the specified +message+ i.e. calls +Kernel#raise(exception, message)+.
+    #
+    # @param [Class,Exception,String,#exception] exception exception to be raised or message to be passed to RuntimeError.
+    # @param [String] message exception message.
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
+    #
+    # @see Kernel#raise
+    # @see #then
     #
-    # Modifies expectation so that when the expected method is called, it raises the specified +exception+ with the specified +message+ i.e. calls Kernel#raise(exception, message).
+    # @overload def raises
+    # @overload def raises(exception)
+    # @overload def raises(exception, message)
+    #
+    # @example Raise specified exception if expected method is invoked.
     #   object = stub()
     #   object.stubs(:expected_method).raises(Exception, 'message')
     #   object.expected_method # => raises exception of class Exception and with message 'message'
-    # Note that if you have a custom exception class with extra constructor parameters, you can pass in an instance of the exception (just as you can for Kernel#raise).
+    #
+    # @example Raise custom exception with extra constructor parameters by passing in an instance of the exception.
     #   object = stub()
     #   object.stubs(:expected_method).raises(MyException.new('message', 1, 2, 3))
     #   object.expected_method # => raises the specified instance of MyException
-    # May be called multiple times on the same expectation. Also see Expectation#then.
+    #
+    # @example Raise different exceptions on consecutive invocations of the expected method.
     #   object = stub()
     #   object.stubs(:expected_method).raises(Exception1).then.raises(Exception2)
     #   object.expected_method # => raises exception of class Exception1
     #   object.expected_method # => raises exception of class Exception2
-    # May be called in conjunction with Expectation#returns on the same expectation.
+    #
+    # @example Raise an exception on first invocation of expected method and then return values on subsequent invocations.
     #   object = stub()
     #   object.stubs(:expected_method).raises(Exception).then.returns(2, 3)
     #   object.expected_method # => raises exception of class Exception1
@@ -314,22 +368,35 @@ module Mocha # :nodoc:
       self
     end
 
-    # :call-seq: throws(tag, object = nil) -> expectation
+    # Modifies expectation so that when the expected method is called, it throws the specified +tag+ with the specific return value +object+ i.e. calls +Kernel#throw(tag, object)+.
+    #
+    # @param [Symbol,String] tag tag to throw to transfer control to the active catch block.
+    # @param [Object] object return value for the catch block.
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
     #
-    # Modifies expectation so that when the expected method is called, it throws the specified +tag+ with the specific return value +object+ i.e. calls Kernel#throw(tag, object).
+    # @see Kernel#throw
+    # @see #then
+    #
+    # @overload def throw(tag)
+    # @overload def throw(tag, object)
+    #
+    # @example Throw tag when expected method is invoked.
     #   object = stub()
     #   object.stubs(:expected_method).throws(:done)
     #   object.expected_method # => throws tag :done
-    # Note you can also pass in an optional return value +object+ (just as you can for Kernel#throw).
+    #
+    # @example Throw tag with return value +object+ c.f. +Kernel#throw+.
     #   object = stub()
     #   object.stubs(:expected_method).throws(:done, 'result')
     #   object.expected_method # => throws tag :done and causes catch block to return 'result'
-    # May be called multiple times on the same expectation. Also see Expectation#then.
+    #
+    # @example Throw different tags on consecutive invocations of the expected method.
     #   object = stub()
     #   object.stubs(:expected_method).throws(:done).then.throws(:continue)
     #   object.expected_method # => throws :done
     #   object.expected_method # => throws :continue
-    # May be called in conjunction with Expectation#returns on the same expectation.
+    #
+    # @example Throw tag on first invocation of expected method and then return values for subsequent invocations.
     #   object = stub()
     #   object.stubs(:expected_method).throws(:done).then.returns(2, 3)
     #   object.expected_method # => throws :done
@@ -340,10 +407,19 @@ module Mocha # :nodoc:
       self
     end
 
-    # :call-seq: then() -> expectation
-    #            then(state_machine.is(state)) -> expectation
+    # @overload def then
+    #   Used as syntactic sugar to improve readability. It has no effect on state of the expectation.
+    # @overload def then(state_machine.is(state_name))
+    #   Used to change the +state_machine+ to the state specified by +state_name+ when the expected invocation occurs.
+    #   @param [StateMachine::State] state_machine.is(state_name) provides a mechanism to change the +state_machine+ into the state specified by +state_name+ when the expected method is invoked.
+    #
+    #   @see API#states
+    #   @see StateMachine
+    #   @see #when
+    #
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
     #
-    # <tt>then()</tt> is used as syntactic sugar to improve readability. It has no effect on state of the expectation.
+    # @example Using {#then} as syntactic sugar when specifying values to be returned and exceptions to be raised on consecutive invocations of the expected method.
     #   object = mock()
     #   object.stubs(:expected_method).returns(1, 2).then.raises(Exception).then.returns(4)
     #   object.expected_method # => 1
@@ -351,9 +427,7 @@ module Mocha # :nodoc:
     #   object.expected_method # => raises exception of class Exception
     #   object.expected_method # => 4
     #
-    # <tt>then(state_machine.is(state))</tt> is used to change the +state_machine+ to the specified +state+ when the invocation occurs.
-    #
-    # See also API#states, StateMachine and Expectation#when.
+    # @example Using {#then} to change the +state+ of a +state_machine+ on the invocation of an expected method.
     #   power = states('power').starts_as('off')
     #
     #   radio = mock('radio')
@@ -371,11 +445,16 @@ module Mocha # :nodoc:
       self
     end
 
-    # :call-seq: when(state_machine.is(state)) -> exception
+    # Constrains the expectation to occur only when the +state_machine+ is in the state specified by +state_name+.
+    #
+    # @param [StateMachine::StatePredicate] state_machine.is(state_name) provides a mechanism to determine whether the +state_machine+ is in the state specified by +state_name+ when the expected method is invoked.
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
     #
-    # Constrains the expectation to occur only when the +state_machine+ is in the named +state+.
+    # @see API#states
+    # @see StateMachine
+    # @see #then
     #
-    # See also API#states, StateMachine#starts_as and Expectation#then.
+    # @example Using {#when} to only allow invocation of methods when "power" state machine is in the "on" state.
     #   power = states('power').starts_as('off')
     #
     #   radio = mock('radio')
@@ -390,17 +469,22 @@ module Mocha # :nodoc:
       self
     end
 
-    # :call-seq: in_sequence(*sequences) -> expectation
+    # Constrains the expectation so that it must be invoked at the current point in the +sequence+.
     #
-    # Constrains this expectation so that it must be invoked at the current point in the sequence.
+    # To expect a sequence of invocations, write the expectations in order and add the +in_sequence(sequence)+ clause to each one.
     #
-    # To expect a sequence of invocations, write the expectations in order and add the in_sequence(sequence) clause to each one.
+    # Expectations in a +sequence+ can have any invocation count.
     #
-    # Expectations in a sequence can have any invocation count.
+    # If an expectation in a sequence is stubbed, rather than expected, it can be skipped in the +sequence+.
     #
-    # If an expectation in a sequence is stubbed, rather than expected, it can be skipped in the sequence.
+    # An expected method can appear in multiple sequences.
     #
-    # See also API#sequence.
+    # @param [*Array<Sequence>] sequences sequences in which expected method should appear.
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
+    #
+    # @see API#sequence
+    #
+    # @example Ensure methods are invoked in a specified order.
     #   breakfast = sequence('breakfast')
     #
     #   egg = mock('egg')
@@ -412,10 +496,10 @@ module Mocha # :nodoc:
       self
     end
 
-    # :stopdoc:
-
+    # @private
     attr_reader :backtrace
 
+    # @private
     def initialize(mock, expected_method_name, backtrace = nil)
       @mock = mock
       @method_matcher = MethodMatcher.new(expected_method_name.to_sym)
@@ -428,42 +512,52 @@ module Mocha # :nodoc:
       @backtrace = backtrace || caller
     end
 
+    # @private
     def add_ordering_constraint(ordering_constraint)
       @ordering_constraints << ordering_constraint
     end
 
+    # @private
     def add_in_sequence_ordering_constraint(sequence)
       sequence.constrain_as_next_in_sequence(self)
     end
 
+    # @private
     def add_side_effect(side_effect)
       @side_effects << side_effect
     end
 
+    # @private
     def perform_side_effects
       @side_effects.each { |side_effect| side_effect.perform }
     end
 
+    # @private
     def in_correct_order?
       @ordering_constraints.all? { |ordering_constraint| ordering_constraint.allows_invocation_now? }
     end
 
+    # @private
     def matches_method?(method_name)
       @method_matcher.match?(method_name)
     end
 
+    # @private
     def match?(actual_method_name, *actual_parameters)
       @method_matcher.match?(actual_method_name) && @parameters_matcher.match?(actual_parameters) && in_correct_order?
     end
 
+    # @private
     def invocations_allowed?
       @cardinality.invocations_allowed?(@invocation_count)
     end
 
+    # @private
     def satisfied?
       @cardinality.satisfied?(@invocation_count)
     end
 
+    # @private
     def invoke
       @invocation_count += 1
       perform_side_effects()
@@ -475,15 +569,18 @@ module Mocha # :nodoc:
       @return_values.next
     end
 
+    # @private
     def verified?(assertion_counter = nil)
       assertion_counter.increment if assertion_counter && @cardinality.needs_verifying?
       @cardinality.verified?(@invocation_count)
     end
 
+    # @private
     def used?
       @cardinality.used?(@invocation_count)
     end
 
+    # @private
     def mocha_inspect
       message = "#{@cardinality.mocha_inspect}, "
       message << case @invocation_count
@@ -498,12 +595,11 @@ module Mocha # :nodoc:
       message
     end
 
+    # @private
     def method_signature
       "#{@mock.mocha_inspect}.#{@method_matcher.mocha_inspect}#{@parameters_matcher.mocha_inspect}"
     end
 
-    # :startdoc:
-
   end
 
 end