Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Generate documentation using YARD instead of RDoc.

- YARD allows for much richer documentation.
- It looks prettier too.
- I hope to remove the dependencies on rdoc & coderay.
  • Loading branch information...
commit 4e28497a0df59b86537cdc689ef3cd11ea6c7c3e 1 parent 5753a8a
James Mead authored March 31, 2012

Showing 34 changed files with 1,070 additions and 663 deletions. Show diff stats Hide diff stats

  1. 2  COPYING.rdoc
  2. 8  README.rdoc
  3. 43  Rakefile
  4. 226  lib/mocha/api.rb
  5. 83  lib/mocha/configuration.rb
  6. 250  lib/mocha/expectation.rb
  7. 139  lib/mocha/mock.rb
  8. 167  lib/mocha/object.rb
  9. 6  lib/mocha/parameter_matchers.rb
  10. 34  lib/mocha/parameter_matchers/all_of.rb
  11. 35  lib/mocha/parameter_matchers/any_of.rb
  12. 23  lib/mocha/parameter_matchers/any_parameters.rb
  13. 31  lib/mocha/parameter_matchers/anything.rb
  14. 60  lib/mocha/parameter_matchers/base.rb
  15. 35  lib/mocha/parameter_matchers/equals.rb
  16. 34  lib/mocha/parameter_matchers/has_entries.rb
  17. 44  lib/mocha/parameter_matchers/has_entry.rb
  18. 32  lib/mocha/parameter_matchers/has_key.rb
  19. 32  lib/mocha/parameter_matchers/has_value.rb
  20. 18  lib/mocha/parameter_matchers/includes.rb
  21. 35  lib/mocha/parameter_matchers/instance_of.rb
  22. 35  lib/mocha/parameter_matchers/is_a.rb
  23. 35  lib/mocha/parameter_matchers/kind_of.rb
  24. 34  lib/mocha/parameter_matchers/not.rb
  25. 8  lib/mocha/parameter_matchers/object.rb
  26. 36  lib/mocha/parameter_matchers/optionally.rb
  27. 17  lib/mocha/parameter_matchers/query_string.rb
  28. 30  lib/mocha/parameter_matchers/regexp_matches.rb
  29. 23  lib/mocha/parameter_matchers/responds_with.rb
  30. 22  lib/mocha/parameter_matchers/yaml_equivalent.rb
  31. 37  lib/mocha/sequence.rb
  32. 107  lib/mocha/state_machine.rb
  33. 9  lib/mocha/stubbing_error.rb
  34. 3  mocha.gemspec
2  COPYING.rdoc
Source Rendered
... ...
@@ -1,3 +1,3 @@
1 1
 Copyright Revieworld Ltd. 2006
2 2
 
3  
-You may use, copy and redistribute this library under the same terms as {Ruby itself}[http://www.ruby-lang.org/en/LICENSE.txt] or under the {MIT license}[/files/MIT-LICENSE.rdoc.html].
  3
+You may use, copy and redistribute this library under the same terms as {Ruby itself}[http://www.ruby-lang.org/en/LICENSE.txt] or under the {file:MIT-LICENSE.rdoc MIT license}.
8  README.rdoc
Source Rendered
@@ -36,9 +36,9 @@ Note that versions 0.9.6 & 0.9.7 of the Rails plugin were broken. As of version
36 36
 
37 37
 == Examples
38 38
 
39  
-* Quick Start - {Usage Examples}[/examples/misc.html]
40  
-* Traditional mocking - {Star Trek Example}[/examples/mocha.html]
41  
-* Setting expectations on real classes - {Order Example}[/examples/stubba.html]
  39
+* Quick Start - {file:misc.rb Usage Examples}
  40
+* Traditional mocking - {file:mocha.rb Star Trek Example}
  41
+* Setting expectations on real classes - {file:stubba.rb Order Example}
42 42
 * More examples on {James Mead's Blog}[http://jamesmead.org/blog/]
43 43
 * {Mailing List Archives}[http://groups.google.com/group/mocha-developer]
44 44
 
@@ -51,4 +51,4 @@ Note that versions 0.9.6 & 0.9.7 of the Rails plugin were broken. As of version
51 51
 
52 52
 Copyright Revieworld Ltd. 2006
53 53
 
54  
-You may use, copy and redistribute this library under the same terms as {Ruby itself}[http://www.ruby-lang.org/en/LICENSE.txt] or under the {MIT license}[/files/MIT-LICENSE.rdoc.html].
  54
+You may use, copy and redistribute this library under the same terms as {Ruby itself}[http://www.ruby-lang.org/en/LICENSE.txt] or under the {file:MIT-LICENSE.rdoc MIT license}.
43  Rakefile
@@ -2,7 +2,7 @@ require "bundler"
2 2
 Bundler::GemHelper.install_tasks
3 3
 require "bundler/setup"
4 4
 
5  
-require 'rdoc/task'
  5
+require 'yard'
6 6
 require 'rake/testtask'
7 7
 
8 8
 desc "Run all tests"
@@ -81,23 +81,15 @@ def benchmark_test_case(klass, iterations)
81 81
   end
82 82
 end
83 83
 
84  
-desc 'Generate RDoc'
85  
-Rake::RDocTask.new('rdoc') do |task|
86  
-  task.generator = 'hanna'
87  
-  task.main = 'README.rdoc'
88  
-  task.title = "Mocha #{Mocha::VERSION}"
89  
-  task.rdoc_dir = 'doc'
90  
-  template = File.expand_path(File.join(File.dirname(__FILE__), "templates", "html_with_google_analytics.rb"))
91  
-  if File.exist?(template)
92  
-    puts "*** Using RDoc template incorporating Google Analytics"
93  
-    task.template = template
94  
-  end
95  
-  task.rdoc_files.include(
96  
-    'README.rdoc',
97  
-    'RELEASE.rdoc',
98  
-    'COPYING.rdoc',
99  
-    'MIT-LICENSE.rdoc',
100  
-    'agiledox.txt',
  84
+desc 'Remove generated documentation'
  85
+task 'clobber_yardoc' do
  86
+  `rm -rf ./doc`
  87
+end
  88
+
  89
+desc 'Generate documentation'
  90
+YARD::Rake::YardocTask.new('yardoc') do |task|
  91
+  task.options = ["--title", "Mocha #{Mocha::VERSION}", "--no-private"]
  92
+  task.files   = [
101 93
     'lib/mocha/api.rb',
102 94
     'lib/mocha/mock.rb',
103 95
     'lib/mocha/expectation.rb',
@@ -105,13 +97,22 @@ Rake::RDocTask.new('rdoc') do |task|
105 97
     'lib/mocha/parameter_matchers.rb',
106 98
     'lib/mocha/parameter_matchers',
107 99
     'lib/mocha/state_machine.rb',
  100
+    'lib/mocha/sequence.rb',
108 101
     'lib/mocha/configuration.rb',
109  
-    'lib/mocha/stubbing_error.rb'
110  
-  )
  102
+    'lib/mocha/stubbing_error.rb',
  103
+    '-',
  104
+    'RELEASE.rdoc',
  105
+    'COPYING.rdoc',
  106
+    'MIT-LICENSE.rdoc',
  107
+    'agiledox.txt',
  108
+    'examples/mocha.rb',
  109
+    'examples/stubba.rb',
  110
+    'examples/misc.rb',
  111
+  ]
111 112
 end
112 113
 
113 114
 desc "Generate documentation"
114  
-task 'generate_docs' => ['clobber_rdoc', 'rdoc', 'examples', 'agiledox.txt']
  115
+task 'generate_docs' => ['clobber_yardoc', 'agiledox.txt', 'yardoc']
115 116
 
116 117
 desc "Publish docs to Github (relies on running 'generate_docs' task and committing changes to master branch)"
117 118
 task 'publish_docs' do
226  lib/mocha/api.rb
@@ -2,40 +2,40 @@
2 2
 require 'mocha/mockery'
3 3
 require 'mocha/sequence'
4 4
 
5  
-module Mocha # :nodoc:
6  
-  
7  
-  # Methods added to Test::Unit::TestCase or equivalent.
  5
+module Mocha
  6
+
  7
+  # Methods added to +Test::Unit::TestCase+ or equivalent.
8 8
   module API
9  
-    
  9
+
10 10
     include ParameterMatchers
11  
-    
12  
-    # :call-seq: mock(name, &block) -> mock object
13  
-    #            mock(expected_methods = {}, &block) -> mock object
14  
-    #            mock(name, expected_methods = {}, &block) -> mock object
15  
-    #
16  
-    # Creates a mock object.
17  
-    #
18  
-    # +name+ is a +String+ identifier for the mock object.
19  
-    #
20  
-    # +expected_methods+ is a +Hash+ with expected method name symbols as keys and corresponding return values as values.
21  
-    #
22  
-    # Note that (contrary to expectations set up by #stub) these expectations <b>must</b> be fulfilled during the test.
23  
-    #   def test_product
24  
-    #     product = mock('ipod_product', :manufacturer => 'ipod', :price => 100)
25  
-    #     assert_equal 'ipod', product.manufacturer
26  
-    #     assert_equal 100, product.price
27  
-    #     # an error will be raised unless both Product#manufacturer and Product#price have been called
28  
-    #   end 
29  
-    #
30  
-    # +block+ is an optional block to be evaluated against the mock object instance, giving an alernative way to set up expectations & stubs.
31  
-    #   def test_product
32  
-    #     product = mock('ipod_product') do
33  
-    #       expects(:manufacturer).returns('ipod')
34  
-    #       expects(:price).returns(100)
  11
+
  12
+    # Builds a new mock object
  13
+    #
  14
+    # @param [String] name identifies mock object in error messages.
  15
+    # @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 {Mock#expects} were called multiple times.
  16
+    # @yield optional block to be evaluated against the mock object instance, giving an alternative way to setup expectations.
  17
+    # @return [Mock] a new mock object
  18
+    #
  19
+    # @overload def mock(name, &block)
  20
+    # @overload def mock(expected_methods_vs_return_values = {}, &block)
  21
+    # @overload def mock(name, expected_methods_vs_return_values = {}, &block)
  22
+    #
  23
+    # @example Using expected_methods_vs_return_values Hash to setup expectations.
  24
+    #   def test_motor_starts_and_stops
  25
+    #     motor = mock('motor', :start => true, :stop => true)
  26
+    #     assert motor.start
  27
+    #     assert motor.stop
  28
+    #     # an error will be raised unless both Motor#start and Motor#stop have been called
  29
+    #   end
  30
+    # @example Using the optional block to setup expectations & stubbed methods.
  31
+    #   def test_motor_starts_and_stops
  32
+    #     motor = mock('motor') do
  33
+    #       expects(:start).with(100.rpm).returns(true)
  34
+    #       stubs(:stop).returns(true)
35 35
     #     end
36  
-    #     assert_equal 'ipod', product.manufacturer
37  
-    #     assert_equal 100, product.price
38  
-    #     # an error will be raised unless both Product#manufacturer and Product#price have been called
  36
+    #     assert motor.start(100.rpm)
  37
+    #     assert motor.stop
  38
+    #     # an error will only be raised if Motor#start(100.rpm) has not been called
39 39
     #   end 
40 40
     def mock(*arguments, &block)
41 41
       name = arguments.shift if arguments.first.is_a?(String)
@@ -44,34 +44,36 @@ def mock(*arguments, &block)
44 44
       mock.expects(expectations)
45 45
       mock
46 46
     end
47  
-    
48  
-    # :call-seq: stub(name, &block) -> mock object
49  
-    #            stub(stubbed_methods = {}, &block) -> mock object
50  
-    #            stub(name, stubbed_methods = {}, &block) -> mock object
51  
-    #
52  
-    # Creates a mock object.
53  
-    #
54  
-    # +name+ is a +String+ identifier for the mock object.
55  
-    #
56  
-    # +stubbed_methods+ is a +Hash+ with stubbed method name symbols as keys and corresponding return values as values.
57  
-    # Note that (contrary to expectations set up by #mock) these expectations <b>need not</b> be fulfilled during the test.
58  
-    #   def test_product
59  
-    #     product = stub('ipod_product', :manufacturer => 'ipod', :price => 100)
60  
-    #     assert_equal 'ipod', product.manufacturer
61  
-    #     assert_equal 100, product.price
62  
-    #     # an error will not be raised even if Product#manufacturer and Product#price have not been called
  47
+
  48
+    # Builds a new mock object
  49
+    #
  50
+    # @param [String] name identifies mock object in error messages.
  51
+    # @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 {Mock#stubs} were called multiple times.
  52
+    # @yield optional block to be evaluated against the mock object instance, giving an alternative way to setup stubbed methods.
  53
+    # @return [Mock] a new mock object
  54
+    #
  55
+    # @overload def stub(name, &block)
  56
+    # @overload def stub(stubbed_methods_vs_return_values = {}, &block)
  57
+    # @overload def stub(name, stubbed_methods_vs_return_values = {}, &block)
  58
+    #
  59
+    # @example Using stubbed_methods_vs_return_values Hash to setup stubbed methods.
  60
+    #   def test_motor_starts_and_stops
  61
+    #     motor = mock('motor', :start => true, :stop => true)
  62
+    #     assert motor.start
  63
+    #     assert motor.stop
  64
+    #     # an error will not be raised even if either Motor#start or Motor#stop has not been called
63 65
     #   end
64 66
     #
65  
-    # +block+ is an optional block to be evaluated against the mock object instance, giving an alernative way to set up expectations & stubs.
66  
-    #   def test_product
67  
-    #     product = stub('ipod_product') do
68  
-    #       stubs(:manufacturer).returns('ipod')
69  
-    #       stubs(:price).returns(100)
  67
+    # @example Using the optional block to setup expectations & stubbed methods.
  68
+    #   def test_motor_starts_and_stops
  69
+    #     motor = mock('motor') do
  70
+    #       expects(:start).with(100.rpm).returns(true)
  71
+    #       stubs(:stop).returns(true)
70 72
     #     end
71  
-    #     assert_equal 'ipod', product.manufacturer
72  
-    #     assert_equal 100, product.price
73  
-    #     # an error will not be raised even if Product#manufacturer and Product#price have not been called
74  
-    #   end
  73
+    #     assert motor.start(100.rpm)
  74
+    #     assert motor.stop
  75
+    #     # an error will only be raised if Motor#start(100.rpm) has not been called
  76
+    #   end 
75 77
     def stub(*arguments, &block)
76 78
       name = arguments.shift if arguments.first.is_a?(String)
77 79
       expectations = arguments.shift || {}
@@ -79,23 +81,24 @@ def stub(*arguments, &block)
79 81
       stub.stubs(expectations)
80 82
       stub
81 83
     end
82  
-    
83  
-    # :call-seq: stub_everything(name, &block) -> mock object
84  
-    #            stub_everything(stubbed_methods = {}, &block) -> mock object
85  
-    #            stub_everything(name, stubbed_methods = {}, &block) -> mock object
86  
-    #
87  
-    # Creates a mock object that accepts calls to any method.
88  
-    #
89  
-    # By default it will return +nil+ for any method call.
90  
-    #
91  
-    # +block+ is a block to be evaluated against the mock object instance, giving an alernative way to set up expectations & stubs.
92  
-    #
93  
-    # +name+ and +stubbed_methods+ work in the same way as for #stub.
94  
-    #   def test_product
95  
-    #     product = stub_everything('ipod_product', :price => 100)
96  
-    #     assert_nil product.manufacturer
97  
-    #     assert_nil product.any_old_method
98  
-    #     assert_equal 100, product.price
  84
+
  85
+    # Builds a mock object that accepts calls to any method. By default it will return +nil+ for any method call.
  86
+    #
  87
+    # @param [String] name identifies mock object in error messages.
  88
+    # @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 {Mock#stubs} were called multiple times.
  89
+    # @yield optional block to be evaluated against the mock object instance, giving an alternative way to setup stubbed methods.
  90
+    # @return [Mock] a new mock object
  91
+    #
  92
+    # @overload def stub_everything(name, &block)
  93
+    # @overload def stub_everything(stubbed_methods_vs_return_values = {}, &block)
  94
+    # @overload def stub_everything(name, stubbed_methods_vs_return_values = {}, &block)
  95
+    #
  96
+    # @example Ignore invocations of irrelevant methods.
  97
+    #   def test_motor_stops
  98
+    #     motor = stub_everything('motor', :stop => true)
  99
+    #     assert_nil motor.irrelevant_method_1 # => no error raised
  100
+    #     assert_nil motor.irrelevant_method_2 # => no error raised
  101
+    #     assert motor.stop
99 102
     #   end
100 103
     def stub_everything(*arguments, &block)
101 104
       name = arguments.shift if arguments.first.is_a?(String)
@@ -105,69 +108,80 @@ def stub_everything(*arguments, &block)
105 108
       stub.stubs(expectations)
106 109
       stub
107 110
     end
108  
-    
109  
-    # :call-seq: sequence(name) -> sequence
  111
+
  112
+    # Builds a new sequence which can be used to constrain the order in which expectations can occur.
110 113
     #
111  
-    # Returns a new sequence that is used to constrain the order in which expectations can occur.
  114
+    # Specify that an expected invocation must occur within a named {Sequence} by using {Expectation#in_sequence}.
112 115
     #
113  
-    # Specify that an expected invocation must occur in within a named +sequence+ by using Expectation#in_sequence.
  116
+    # @return [Sequence] a new sequence
114 117
     #
115  
-    # See also Expectation#in_sequence.
  118
+    # @see Expectation#in_sequence
  119
+    #
  120
+    # @example Ensure methods on egg are invoked in correct order.
116 121
     #   breakfast = sequence('breakfast')
117 122
     #
118  
-    #   egg = mock('egg')
119  
-    #   egg.expects(:crack).in_sequence(breakfast)
120  
-    #   egg.expects(:fry).in_sequence(breakfast)
121  
-    #   egg.expects(:eat).in_sequence(breakfast)
  123
+    #   egg = mock('egg') do
  124
+    #     expects(:crack).in_sequence(breakfast)
  125
+    #     expects(:fry).in_sequence(breakfast)
  126
+    #     expects(:eat).in_sequence(breakfast)
  127
+    #   end
122 128
     def sequence(name)
123 129
       Sequence.new(name)
124 130
     end
125  
-    
126  
-    # :call-seq: states(name) -> state_machine
  131
+
  132
+    # Builds a new state machine which can be used to constrain the order in which expectations can occur.
127 133
     #
128  
-    # Returns a new +state_machine+ that is used to constrain the order in which expectations can occur.
  134
+    # Specify the initial state of the state machine by using {StateMachine#starts_as}.
129 135
     #
130  
-    # Specify the initial +state+ of the +state_machine+ by using StateMachine#starts_as.
  136
+    # Specify that an expected invocation should change the state of the state machine by using {Expectation#then}.
131 137
     #
132  
-    # Specify that an expected invocation should change the +state+ of the +state_machine+ by using Expectation#then.
  138
+    # Specify that an expected invocation should be constrained to occur within a particular +state+ by using {Expectation#when}.
133 139
     #
134  
-    # Specify that an expected invocation should be constrained to occur within a particular +state+ by using Expectation#when.
  140
+    # A test can contain multiple state machines.
135 141
     #
136  
-    # A test can contain multiple +state_machines+.
  142
+    # @return [StateMachine] a new state machine
137 143
     #
138  
-    # See also Expectation#then, Expectation#when and StateMachine.
  144
+    # @see Expectation#then
  145
+    # @see Expectation#when
  146
+    # @see StateMachine
  147
+    # @example Constrain expected invocations to occur in particular states.
139 148
     #   power = states('power').starts_as('off')
140 149
     #
141  
-    #   radio = mock('radio')
142  
-    #   radio.expects(:switch_on).then(power.is('on'))
143  
-    #   radio.expects(:select_channel).with('BBC Radio 4').when(power.is('on'))
144  
-    #   radio.expects(:adjust_volume).with(+5).when(power.is('on'))
145  
-    #   radio.expects(:select_channel).with('BBC World Service').when(power.is('on'))
146  
-    #   radio.expects(:adjust_volume).with(-5).when(power.is('on'))
147  
-    #   radio.expects(:switch_off).then(power.is('off'))
  150
+    #   radio = mock('radio') do
  151
+    #     expects(:switch_on).then(power.is('on'))
  152
+    #     expects(:select_channel).with('BBC Radio 4').when(power.is('on'))
  153
+    #     expects(:adjust_volume).with(+5).when(power.is('on'))
  154
+    #     expects(:select_channel).with('BBC World Service').when(power.is('on'))
  155
+    #     expects(:adjust_volume).with(-5).when(power.is('on'))
  156
+    #     expects(:switch_off).then(power.is('off'))
  157
+    #   end
148 158
     def states(name)
149 159
       Mockery.instance.new_state_machine(name)
150 160
     end
151  
-    
152  
-    def mocha_setup # :nodoc:
  161
+
  162
+    # @private
  163
+    def mocha_setup
153 164
     end
154  
-    
155  
-    def mocha_verify(assertion_counter = nil) # :nodoc:
  165
+
  166
+    # @private
  167
+    def mocha_verify(assertion_counter = nil)
156 168
       Mockery.instance.verify(assertion_counter)
157 169
     end
158  
-    
159  
-    def mocha_teardown # :nodoc:
  170
+
  171
+    # @private
  172
+    def mocha_teardown
160 173
       Mockery.instance.teardown
161 174
       Mockery.reset_instance
162 175
     end
163  
-    
  176
+
164 177
   end
165  
-  
  178
+
  179
+  # @private
166 180
   def self.const_missing(name)
167 181
     return super unless name == :Standalone
168 182
     require 'mocha/deprecation'
169 183
     Deprecation.warning "Mocha::Standalone has been renamed to Mocha::API"
170 184
     return API
171 185
   end
172  
-  
  186
+
173 187
 end
83  lib/mocha/configuration.rb
... ...
@@ -1,62 +1,70 @@
1  
-module Mocha # :nodoc:
2  
-  
3  
-  # Configuration settings
  1
+module Mocha
  2
+
  3
+  # Configuration settings.
4 4
   class Configuration
5  
-    
6  
-    DEFAULTS = { :stubbing_method_unnecessarily => :allow, :stubbing_method_on_non_mock_object => :allow, :stubbing_non_existent_method => :allow, :stubbing_non_public_method => :allow }
7  
-    
  5
+
  6
+    DEFAULTS = {
  7
+      :stubbing_method_unnecessarily => :allow,
  8
+      :stubbing_method_on_non_mock_object => :allow,
  9
+      :stubbing_non_existent_method => :allow,
  10
+      :stubbing_non_public_method => :allow
  11
+    }
  12
+
8 13
     class << self
9  
-    
10  
-      # :call-seq: allow(action, &block)
  14
+
  15
+      # Allow the specified +action+.
11 16
       #
12  
-      # Allow the specified <tt>action</tt> (as a symbol).
13  
-      # 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>.
14  
-      # 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.
  17
+      # @param [Symbol] action one of +:stubbing_method_unnecessarily+, +:stubbing_method_on_non_mock_object+, +:stubbing_non_existent_method+, +:stubbing_non_public_method+.
  18
+      # @yield optional block during which the configuration change will be changed before being returned to its original value at the end of the block.
15 19
       def allow(action, &block)
16 20
         change_config action, :allow, &block
17 21
       end
18  
-    
19  
-      def allow?(action) # :nodoc:
  22
+
  23
+      # @private
  24
+      def allow?(action)
20 25
         configuration[action] == :allow
21 26
       end
22  
-    
23  
-      # :call-seq: warn_when(action, &block)
  27
+
  28
+      # Warn if the specified +action+ is attempted.
24 29
       #
25  
-      # Warn if the specified <tt>action</tt> (as a symbol) is attempted.
26  
-      # 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>.
27  
-      # 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.
  30
+      # @param [Symbol] action one of +:stubbing_method_unnecessarily+, +:stubbing_method_on_non_mock_object+, +:stubbing_non_existent_method+, +:stubbing_non_public_method+.
  31
+      # @yield optional block during which the configuration change will be changed before being returned to its original value at the end of the block.
28 32
       def warn_when(action, &block)
29 33
         change_config action, :warn, &block
30 34
       end
31  
-    
32  
-      def warn_when?(action) # :nodoc:
  35
+
  36
+      # @private
  37
+      def warn_when?(action)
33 38
         configuration[action] == :warn
34 39
       end
35  
-    
36  
-      # :call-seq: prevent(action, &block)
  40
+
  41
+      # Raise a {StubbingError} if if the specified +action+ is attempted.
37 42
       #
38  
-      # Raise a StubbingError if the specified <tt>action</tt> (as a symbol) is attempted.
39  
-      # 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>.
40  
-      # 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.
  43
+      # @param [Symbol] action one of +:stubbing_method_unnecessarily+, +:stubbing_method_on_non_mock_object+, +:stubbing_non_existent_method+, +:stubbing_non_public_method+.
  44
+      # @yield optional block during which the configuration change will be changed before being returned to its original value at the end of the block.
41 45
       def prevent(action, &block)
42 46
         change_config action, :prevent, &block
43 47
       end
44  
-    
45  
-      def prevent?(action) # :nodoc:
  48
+
  49
+      # @private
  50
+      def prevent?(action)
46 51
         configuration[action] == :prevent
47 52
       end
48  
-    
49  
-      def reset_configuration # :nodoc:
  53
+
  54
+      # @private
  55
+      def reset_configuration
50 56
         @configuration = nil
51 57
       end
52  
-    
  58
+
53 59
       private
54  
-    
55  
-      def configuration # :nodoc:
  60
+
  61
+      # @private
  62
+      def configuration
56 63
         @configuration ||= DEFAULTS.dup
57 64
       end
58 65
 
59  
-      def change_config(action, new_value, &block) # :nodoc:
  66
+      # @private
  67
+      def change_config(action, new_value, &block)
60 68
         if block_given?
61 69
           temporarily_change_config action, new_value, &block
62 70
         else
@@ -64,16 +72,17 @@ def change_config(action, new_value, &block) # :nodoc:
64 72
         end
65 73
       end
66 74
 
67  
-      def temporarily_change_config(action, new_value, &block) # :nodoc:
  75
+      # @private
  76
+      def temporarily_change_config(action, new_value, &block)
68 77
         original_value = configuration[action]
69 78
         configuration[action] = new_value
70 79
         yield
71 80
       ensure
72 81
         configuration[action] = original_value
73 82
       end
74  
-    
  83
+
75 84
     end
76  
-    
  85
+
77 86
   end
78  
-  
  87
+
79 88
 end
250  lib/mocha/expectation.rb
@@ -10,16 +10,17 @@
10 10
 require 'mocha/change_state_side_effect'
11 11
 require 'mocha/cardinality'
12 12
 
13  
-module Mocha # :nodoc:
  13
+module Mocha
14 14
 
15  
-  # Methods on expectations returned from Mock#expects, Mock#stubs, Object#expects and Object#stubs.
  15
+  # Methods on expectations returned from {Mock#expects}, {Mock#stubs}, {ObjectMethods#expects} and {ObjectMethods#stubs}.
16 16
   class Expectation
17 17
 
18  
-    # :call-seq: times(range) -> expectation
19  
-    #
20 18
     # Modifies expectation so that the number of calls to the expected method must be within a specific +range+.
21 19
     #
22  
-    # +range+ can be specified as an exact integer or as a range of integers
  20
+    # @param [Range,Integer] range specifies the allowable range in the number of expected invocations.
  21
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
  22
+    #
  23
+    # @example Specifying a specific number of expected invocations.
23 24
     #   object = mock()
24 25
     #   object.expects(:expected_method).times(3)
25 26
     #   3.times { object.expected_method }
@@ -30,6 +31,7 @@ class Expectation
30 31
     #   2.times { object.expected_method }
31 32
     #   # => verify fails
32 33
     #
  34
+    # @example Specifying a range in the number of expected invocations.
33 35
     #   object = mock()
34 36
     #   object.expects(:expected_method).times(2..4)
35 37
     #   3.times { object.expected_method }
@@ -44,9 +46,11 @@ def times(range)
44 46
       self
45 47
     end
46 48
 
47  
-    # :call-seq: twice() -> expectation
48  
-    #
49 49
     # Modifies expectation so that the expected method must be called exactly twice.
  50
+    #
  51
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
  52
+    #
  53
+    # @example Expected method must be invoked exactly twice.
50 54
     #   object = mock()
51 55
     #   object.expects(:expected_method).twice
52 56
     #   object.expected_method
@@ -57,8 +61,7 @@ def times(range)
57 61
     #   object.expects(:expected_method).twice
58 62
     #   object.expected_method
59 63
     #   object.expected_method
60  
-    #   object.expected_method
61  
-    #   # => verify fails
  64
+    #   object.expected_method # => unexpected invocation
62 65
     #
63 66
     #   object = mock()
64 67
     #   object.expects(:expected_method).twice
@@ -69,10 +72,13 @@ def twice
69 72
       self
70 73
     end
71 74
 
72  
-    # :call-seq: once() -> expectation
73  
-    #
74 75
     # Modifies expectation so that the expected method must be called exactly once.
  76
+    #
75 77
     # Note that this is the default behaviour for an expectation, but you may wish to use it for clarity/emphasis.
  78
+    #
  79
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
  80
+    #
  81
+    # @example Expected method must be invoked exactly once.
76 82
     #   object = mock()
77 83
     #   object.expects(:expected_method).once
78 84
     #   object.expected_method
@@ -81,8 +87,7 @@ def twice
81 87
     #   object = mock()
82 88
     #   object.expects(:expected_method).once
83 89
     #   object.expected_method
84  
-    #   object.expected_method
85  
-    #   # => verify fails
  90
+    #   object.expected_method # => unexpected invocation
86 91
     #
87 92
     #   object = mock()
88 93
     #   object.expects(:expected_method).once
@@ -92,13 +97,14 @@ def once
92 97
       self
93 98
     end
94 99
 
95  
-    # :call-seq: never() -> expectation
96  
-    #
97 100
     # Modifies expectation so that the expected method must never be called.
  101
+    #
  102
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
  103
+    #
  104
+    # @example Expected method must never be called.
98 105
     #   object = mock()
99 106
     #   object.expects(:expected_method).never
100  
-    #   object.expected_method
101  
-    #   # => verify fails
  107
+    #   object.expected_method # => unexpected invocation
102 108
     #
103 109
     #   object = mock()
104 110
     #   object.expects(:expected_method).never
@@ -108,9 +114,12 @@ def never
108 114
       self
109 115
     end
110 116
 
111  
-    # :call-seq: at_least(minimum_number_of_times) -> expectation
112  
-    #
113 117
     # Modifies expectation so that the expected method must be called at least a +minimum_number_of_times+.
  118
+    #
  119
+    # @param [Integer] minimum_number_of_times minimum number of expected invocations.
  120
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
  121
+    #
  122
+    # @example Expected method must be called at least twice.
114 123
     #   object = mock()
115 124
     #   object.expects(:expected_method).at_least(2)
116 125
     #   3.times { object.expected_method }
@@ -125,9 +134,11 @@ def at_least(minimum_number_of_times)
125 134
       self
126 135
     end
127 136
 
128  
-    # :call-seq: at_least_once() -> expectation
129  
-    #
130 137
     # Modifies expectation so that the expected method must be called at least once.
  138
+    #
  139
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
  140
+    #
  141
+    # @example Expected method must be called at least once.
131 142
     #   object = mock()
132 143
     #   object.expects(:expected_method).at_least_once
133 144
     #   object.expected_method
@@ -141,9 +152,12 @@ def at_least_once
141 152
       self
142 153
     end
143 154
 
144  
-    # :call-seq: at_most(maximum_number_of_times) -> expectation
145  
-    #
146 155
     # Modifies expectation so that the expected method must be called at most a +maximum_number_of_times+.
  156
+    #
  157
+    # @param [Integer] maximum_number_of_times maximum number of expected invocations.
  158
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
  159
+    #
  160
+    # @example Expected method must be called at most twice.
147 161
     #   object = mock()
148 162
     #   object.expects(:expected_method).at_most(2)
149 163
     #   2.times { object.expected_method }
@@ -151,16 +165,17 @@ def at_least_once
151 165
     #
152 166
     #   object = mock()
153 167
     #   object.expects(:expected_method).at_most(2)
154  
-    #   3.times { object.expected_method }
155  
-    #   # => verify fails
  168
+    #   3.times { object.expected_method } # => unexpected invocation
156 169
     def at_most(maximum_number_of_times)
157 170
       @cardinality = Cardinality.at_most(maximum_number_of_times)
158 171
       self
159 172
     end
160 173
 
161  
-    # :call-seq: at_most_once() -> expectation
162  
-    #
163 174
     # Modifies expectation so that the expected method must be called at most once.
  175
+    #
  176
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
  177
+    #
  178
+    # @example Expected method must be called at most once.
164 179
     #   object = mock()
165 180
     #   object.expects(:expected_method).at_most_once
166 181
     #   object.expected_method
@@ -168,16 +183,23 @@ def at_most(maximum_number_of_times)
168 183
     #
169 184
     #   object = mock()
170 185
     #   object.expects(:expected_method).at_most_once
171  
-    #   2.times { object.expected_method }
172  
-    #   # => verify fails
  186
+    #   2.times { object.expected_method } # => unexpected invocation
173 187
     def at_most_once()
174 188
       at_most(1)
175 189
       self
176 190
     end
177 191
 
178  
-    # :call-seq: with(*expected_parameters, &matching_block) -> expectation
179  
-    #
180 192
     # Modifies expectation so that the expected method must be called with +expected_parameters+.
  193
+    #
  194
+    # May be used with parameter matchers in {ParameterMatchers}.
  195
+    #
  196
+    # @param [*Array] expected_parameters parameters expected.
  197
+    # @yield optional block specifying custom matching.
  198
+    # @yieldparam [*Array] actual_parameters parameters with which expected method was invoked.
  199
+    # @yieldreturn [Boolean] +true+ if +actual_parameters+ are acceptable.
  200
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
  201
+    #
  202
+    # @example Expected method must be called with expected parameters.
181 203
     #   object = mock()
182 204
     #   object.expects(:expected_method).with(:param1, :param2)
183 205
     #   object.expected_method(:param1, :param2)
@@ -187,10 +209,8 @@ def at_most_once()
187 209
     #   object.expects(:expected_method).with(:param1, :param2)
188 210
     #   object.expected_method(:param3)
189 211
     #   # => verify fails
190  
-    # May be used with parameter matchers in Mocha::ParameterMatchers.
191 212
     #
192  
-    # If a +matching_block+ is given, the block is called with the parameters passed to the expected method.
193  
-    # The expectation is matched if the block evaluates to +true+.
  213
+    # @example Expected method must be called with a value divisible by 4.
194 214
     #   object = mock()
195 215
     #   object.expects(:expected_method).with() { |value| value % 4 == 0 }
196 216
     #   object.expected_method(16)
@@ -205,15 +225,22 @@ def with(*expected_parameters, &matching_block)
205 225
       self
206 226
     end
207 227
 
208  
-    # :call-seq: yields(*parameters) -> expectation
209  
-    #
210 228
     # Modifies expectation so that when the expected method is called, it yields with the specified +parameters+.
  229
+    #
  230
+    # May be called multiple times on the same expectation for consecutive invocations.
  231
+    #
  232
+    # @param [*Array] parameters parameters to be yielded.
  233
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
  234
+    # @see #then
  235
+    #
  236
+    # @example Yield parameters when expected method is invoked.
211 237
     #   object = mock()
212 238
     #   object.expects(:expected_method).yields('result')
213 239
     #   yielded_value = nil
214 240
     #   object.expected_method { |value| yielded_value = value }
215 241
     #   yielded_value # => 'result'
216  
-    # May be called multiple times on the same expectation for consecutive invocations. Also see Expectation#then.
  242
+    #
  243
+    # @example Yield different parameters on different invocations of the expected method.
217 244
     #   object = mock()
218 245
     #   object.stubs(:expected_method).yields(1).then.yields(2)
219 246
     #   yielded_values_from_first_invocation = []
@@ -227,18 +254,20 @@ def yields(*parameters)
227 254
       self
228 255
     end
229 256
 
230  
-    # :call-seq: multiple_yields(*parameter_groups) -> expectation
231  
-    #
232 257
     # Modifies expectation so that when the expected method is called, it yields multiple times per invocation with the specified +parameter_groups+.
233 258
     #
234  
-    # 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.
  259
+    # @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.
  260
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
  261
+    # @see #then
235 262
     #
  263
+    # @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.
236 264
     #   object = mock()
237 265
     #   object.expects(:expected_method).multiple_yields(['result_1', 'result_2'], ['result_3'])
238 266
     #   yielded_values = []
239 267
     #   object.expected_method { |*values| yielded_values << values }
240 268
     #   yielded_values # => [['result_1', 'result_2'], ['result_3]]
241  
-    # May be called multiple times on the same expectation for consecutive invocations. Also see Expectation#then.
  269
+    #
  270
+    # @example Yield different groups of parameters on different invocations of the expected method.
242 271
     #   object = mock()
243 272
     #   object.stubs(:expected_method).multiple_yields([1, 2], [3]).then.multiple_yields([4], [5, 6])
244 273
     #   yielded_values_from_first_invocation = []
@@ -252,32 +281,43 @@ def multiple_yields(*parameter_groups)
252 281
       self
253 282
     end
254 283
 
255  
-    # :call-seq: returns(value) -> expectation
256  
-    #            returns(*values) -> expectation
257  
-    #
258 284
     # Modifies expectation so that when the expected method is called, it returns the specified +value+.
  285
+    #
  286
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
  287
+    # @see #then
  288
+    #
  289
+    # @overload def returns(value)
  290
+    #   @param [Object] value value to return on invocation of expected method.
  291
+    # @overload def returns(*values)
  292
+    #   @param [*Array] values values to return on consecutive invocations of expected method.
  293
+    #
  294
+    # @example Return the same value on every invocation.
259 295
     #   object = mock()
260 296
     #   object.stubs(:stubbed_method).returns('result')
261 297
     #   object.stubbed_method # => 'result'
262 298
     #   object.stubbed_method # => 'result'
263  
-    # If multiple +values+ are given, these are returned in turn on consecutive calls to the method.
  299
+    #
  300
+    # @example Return a different value on consecutive invocations.
264 301
     #   object = mock()
265 302
     #   object.stubs(:stubbed_method).returns(1, 2)
266 303
     #   object.stubbed_method # => 1
267 304
     #   object.stubbed_method # => 2
268  
-    # May be called multiple times on the same expectation. Also see Expectation#then.
  305
+    #
  306
+    # @example Alternative way to return a different value on consecutive invocations.
269 307
     #   object = mock()
270 308
     #   object.stubs(:expected_method).returns(1, 2).then.returns(3)
271 309
     #   object.expected_method # => 1
272 310
     #   object.expected_method # => 2
273 311
     #   object.expected_method # => 3
274  
-    # May be called in conjunction with Expectation#raises on the same expectation.
  312
+    #
  313
+    # @example May be called in conjunction with {#raises} on the same expectation.
275 314
     #   object = mock()
276 315
     #   object.stubs(:expected_method).returns(1, 2).then.raises(Exception)
277 316
     #   object.expected_method # => 1
278 317
     #   object.expected_method # => 2
279 318
     #   object.expected_method # => raises exception of class Exception1
280  
-    # Note that in Ruby a method returning multiple values is exactly equivalent to a method returning an Array of those values.
  319
+    #
  320
+    # @example Note that in Ruby a method returning multiple values is exactly equivalent to a method returning an +Array+ of those values.
281 321
     #   object = mock()
282 322
     #   object.stubs(:expected_method).returns([1, 2])
283 323
     #   x, y = object.expected_method
@@ -288,22 +328,36 @@ def returns(*values)
288 328
       self
289 329
     end
290 330
 
291  
-    # :call-seq: raises(exception = RuntimeError, message = nil) -> expectation
  331
+    # 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)+.
  332
+    #
  333
+    # @param [Class,Exception,String,#exception] exception exception to be raised or message to be passed to RuntimeError.
  334
+    # @param [String] message exception message.
  335
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
  336
+    #
  337
+    # @see Kernel#raise
  338
+    # @see #then
292 339
     #
293  
-    # 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).
  340
+    # @overload def raises
  341
+    # @overload def raises(exception)
  342
+    # @overload def raises(exception, message)
  343
+    #
  344
+    # @example Raise specified exception if expected method is invoked.
294 345
     #   object = stub()
295 346
     #   object.stubs(:expected_method).raises(Exception, 'message')
296 347
     #   object.expected_method # => raises exception of class Exception and with message 'message'
297  
-    # 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).
  348
+    #
  349
+    # @example Raise custom exception with extra constructor parameters by passing in an instance of the exception.
298 350
     #   object = stub()
299 351
     #   object.stubs(:expected_method).raises(MyException.new('message', 1, 2, 3))
300 352
     #   object.expected_method # => raises the specified instance of MyException
301  
-    # May be called multiple times on the same expectation. Also see Expectation#then.
  353
+    #
  354
+    # @example Raise different exceptions on consecutive invocations of the expected method.
302 355
     #   object = stub()
303 356
     #   object.stubs(:expected_method).raises(Exception1).then.raises(Exception2)
304 357
     #   object.expected_method # => raises exception of class Exception1
305 358
     #   object.expected_method # => raises exception of class Exception2
306  
-    # May be called in conjunction with Expectation#returns on the same expectation.
  359
+    #
  360
+    # @example Raise an exception on first invocation of expected method and then return values on subsequent invocations.
307 361
     #   object = stub()
308 362
     #   object.stubs(:expected_method).raises(Exception).then.returns(2, 3)
309 363
     #   object.expected_method # => raises exception of class Exception1
@@ -314,22 +368,35 @@ def raises(exception = RuntimeError, message = nil)
314 368
       self
315 369
     end
316 370
 
317  
-    # :call-seq: throws(tag, object = nil) -> expectation
  371
+    # 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)+.
  372
+    #
  373
+    # @param [Symbol,String] tag tag to throw to transfer control to the active catch block.
  374
+    # @param [Object] object return value for the catch block.
  375
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
318 376
     #
319  
-    # 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).
  377
+    # @see Kernel#throw
  378
+    # @see #then
  379
+    #
  380
+    # @overload def throw(tag)
  381
+    # @overload def throw(tag, object)
  382
+    #
  383
+    # @example Throw tag when expected method is invoked.
320 384
     #   object = stub()
321 385
     #   object.stubs(:expected_method).throws(:done)
322 386
     #   object.expected_method # => throws tag :done
323  
-    # Note you can also pass in an optional return value +object+ (just as you can for Kernel#throw).
  387
+    #
  388
+    # @example Throw tag with return value +object+ c.f. +Kernel#throw+.
324 389
     #   object = stub()
325 390
     #   object.stubs(:expected_method).throws(:done, 'result')
326 391
     #   object.expected_method # => throws tag :done and causes catch block to return 'result'
327  
-    # May be called multiple times on the same expectation. Also see Expectation#then.
  392
+    #
  393
+    # @example Throw different tags on consecutive invocations of the expected method.
328 394
     #   object = stub()
329 395
     #   object.stubs(:expected_method).throws(:done).then.throws(:continue)
330 396
     #   object.expected_method # => throws :done
331 397
     #   object.expected_method # => throws :continue
332  
-    # May be called in conjunction with Expectation#returns on the same expectation.
  398
+    #
  399
+    # @example Throw tag on first invocation of expected method and then return values for subsequent invocations.
333 400
     #   object = stub()
334 401
     #   object.stubs(:expected_method).throws(:done).then.returns(2, 3)
335 402
     #   object.expected_method # => throws :done
@@ -340,10 +407,19 @@ def throws(tag, object = nil)
340 407
       self
341 408
     end
342 409
 
343  
-    # :call-seq: then() -> expectation
344  
-    #            then(state_machine.is(state)) -> expectation
  410
+    # @overload def then
  411
+    #   Used as syntactic sugar to improve readability. It has no effect on state of the expectation.
  412
+    # @overload def then(state_machine.is(state_name))
  413
+    #   Used to change the +state_machine+ to the state specified by +state_name+ when the expected invocation occurs.
  414
+    #   @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.
  415
+    #
  416
+    #   @see API#states
  417
+    #   @see StateMachine
  418
+    #   @see #when
  419
+    #
  420
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
345 421
     #
346  
-    # <tt>then()</tt> is used as syntactic sugar to improve readability. It has no effect on state of the expectation.
  422
+    # @example Using {#then} as syntactic sugar when specifying values to be returned and exceptions to be raised on consecutive invocations of the expected method.
347 423
     #   object = mock()
348 424
     #   object.stubs(:expected_method).returns(1, 2).then.raises(Exception).then.returns(4)
349 425
     #   object.expected_method # => 1
@@ -351,9 +427,7 @@ def throws(tag, object = nil)
351 427
     #   object.expected_method # => raises exception of class Exception
352 428
     #   object.expected_method # => 4
353 429
     #
354  
-    # <tt>then(state_machine.is(state))</tt> is used to change the +state_machine+ to the specified +state+ when the invocation occurs.
355  
-    #
356  
-    # See also API#states, StateMachine and Expectation#when.
  430
+    # @example Using {#then} to change the +state+ of a +state_machine+ on the invocation of an expected method.
357 431
     #   power = states('power').starts_as('off')
358 432
     #
359 433
     #   radio = mock('radio')
@@ -371,11 +445,16 @@ def then(*parameters)
371 445
       self
372 446
     end
373 447
 
374  
-    # :call-seq: when(state_machine.is(state)) -> exception
  448
+    # Constrains the expectation to occur only when the +state_machine+ is in the state specified by +state_name+.
  449
+    #
  450
+    # @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.
  451
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
375 452
     #
376  
-    # Constrains the expectation to occur only when the +state_machine+ is in the named +state+.
  453
+    # @see API#states
  454
+    # @see StateMachine
  455
+    # @see #then
377 456
     #
378  
-    # See also API#states, StateMachine#starts_as and Expectation#then.
  457
+    # @example Using {#when} to only allow invocation of methods when "power" state machine is in the "on" state.
379 458
     #   power = states('power').starts_as('off')
380 459
     #
381 460
     #   radio = mock('radio')
@@ -390,17 +469,22 @@ def when(state_predicate)
390 469
       self
391 470
     end
392 471
 
393  
-    # :call-seq: in_sequence(*sequences) -> expectation
  472
+    # Constrains the expectation so that it must be invoked at the current point in the +sequence+.
394 473
     #
395  
-    # Constrains this expectation so that it must be invoked at the current point in the sequence.
  474
+    # To expect a sequence of invocations, write the expectations in order and add the +in_sequence(sequence)+ clause to each one.
396 475
     #
397  
-    # To expect a sequence of invocations, write the expectations in order and add the in_sequence(sequence) clause to each one.
  476
+    # Expectations in a +sequence+ can have any invocation count.
398 477
     #
399  
-    # Expectations in a sequence can have any invocation count.
  478
+    # If an expectation in a sequence is stubbed, rather than expected, it can be skipped in the +sequence+.
400 479
     #
401  
-    # If an expectation in a sequence is stubbed, rather than expected, it can be skipped in the sequence.
  480
+    # An expected method can appear in multiple sequences.
402 481
     #
403  
-    # See also API#sequence.
  482
+    # @param [*Array<Sequence>] sequences sequences in which expected method should appear.
  483
+    # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
  484
+    #
  485
+    # @see API#sequence
  486
+    #
  487
+    # @example Ensure methods are invoked in a specified order.
404 488
     #   breakfast = sequence('breakfast')
405 489
     #
406 490
     #   egg = mock('egg')
@@ -412,10 +496,10 @@ def in_sequence(*sequences)
412 496
       self
413 497
     end
414 498
 
415  
-    # :stopdoc:
416  
-
  499
+    # @private
417 500
     attr_reader :backtrace
418 501
 
  502
+    # @private
419 503
     def initialize(mock, expected_method_name, backtrace = nil)
420 504
       @mock = mock
421 505
       @method_matcher = MethodMatcher.new(expected_method_name.to_sym)
@@ -428,42 +512,52 @@ def initialize(mock, expected_method_name, backtrace = nil)
428 512
       @backtrace = backtrace || caller
429 513
     end
430 514
 
  515
+    # @private
431 516
     def add_ordering_constraint(ordering_constraint)
432 517
       @ordering_constraints << ordering_constraint
433 518
     end
434 519
 
  520
+    # @private
435 521
     def add_in_sequence_ordering_constraint(sequence)
436 522
       sequence.constrain_as_next_in_sequence(self)
437 523
     end
438 524
 
  525
+    # @private
439 526
     def add_side_effect(side_effect)
440 527
       @side_effects << side_effect
441 528
     end
442 529
 
  530
+    # @private
443 531
     def perform_side_effects
444 532
       @side_effects.each { |side_effect| side_effect.perform }
445 533
     end
446 534
 
  535
+    # @private
447 536
     def in_correct_order?
448 537
       @ordering_constraints.all? { |ordering_constraint| ordering_constraint.allows_invocation_now? }
449 538
     end
450 539
 
  540
+    # @private
451 541
     def matches_method?(method_name)
452 542
       @method_matcher.match?(method_name)
453 543
     end
454 544
 
  545
+    # @private
455 546
     def match?(actual_method_name, *actual_parameters)
456 547
       @method_matcher.match?(actual_method_name) && @parameters_matcher.match?(actual_parameters) && in_correct_order?
457 548
     end
458 549
 
  550
+    # @private
459 551
     def invocations_allowed?
460 552
       @cardinality.invocations_allowed?(@invocation_count)
461 553
     end
462 554
 
  555
+    # @private
463 556
     def satisfied?
464 557
       @cardinality.satisfied?(@invocation_count)
465 558
     end
466 559
 
  560
+    # @private
467 561
     def invoke
468 562
       @invocation_count += 1
469 563
       perform_side_effects()
@@ -475,15 +569,18 @@ def invoke
475 569
       @return_values.next
476 570
     end
477 571
 
  572
+    # @private
478 573
     def verified?(assertion_counter = nil)
479 574
       assertion_counter.increment if assertion_counter && @cardinality.needs_verifying?
480 575
       @cardinality.verified?(@invocation_count)
481 576
     end
482 577
 
  578
+    # @private
483 579
     def used?
484 580
       @cardinality.used?(@invocation_count)
485 581
     end
486 582
 
  583
+    # @private
487 584
     def mocha_inspect
488 585
       message = "#{@cardinality.mocha_inspect}, "
489 586
       message << case @invocation_count
@@ -498,12 +595,11 @@ def mocha_inspect
498 595
       message
499 596
     end
500 597
 
  598
+    # @private
501 599
     def method_signature
502 600
       "#{@mock.mocha_inspect}.#{@method_matcher.mocha_inspect}#{@parameters_matcher.mocha_inspect}"
503 601
     end
504 602
 
505  
-    # :startdoc:
506  
-
507 603
   end
508 604
 
509 605
 end
139  lib/mocha/mock.rb
@@ -7,37 +7,47 @@
7 7
 require 'mocha/unexpected_invocation'
8 8
 require 'mocha/argument_iterator'
9 9
 
10  
-module Mocha # :nodoc:
  10
+module Mocha
11 11
 
12 12
   # Traditional mock object.
13 13
   #
14  
-  # Methods return an Expectation which can be further modified by methods on Expectation.
  14
+  # All methods return an {Expectation} which can be further modified by methods on {Expectation}.
15 15
   class Mock
16 16
 
17  
-    # :call-seq: expects(method_name) -> expectation
18  
-    #            expects(method_names_vs_return_values) -> last expectation
  17
+    # Adds an expectation that the specified method must be called exactly once with any parameters.
19 18
     #
20  
-    # Adds an expectation that a method identified by +method_name+ Symbol/String must be called exactly once with any parameters.
21  
-    # Returns the new expectation which can be further modified by methods on Expectation.
22  
-    #   object = mock()
23  
-    #   object.expects(:method1)
24  
-    #   object.method1
25  
-    #   # no error raised
  19
+    # @param [Symbol,String] method_name name of expected method
  20
+    # @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.
26 21
     #
  22
+    # @overload def expects(method_name)
  23
+    # @overload def expects(expected_methods_vs_return_values)
  24
+    # @return [Expectation] last-built expectation which can be further modified by methods on {Expectation}.
  25
+    #
  26
+    # @example Expected method invoked once so no error raised
27 27
     #   object = mock()
28  
-    #   object.expects(:method1)
29  
-    #   # error raised, because method1 not called exactly once
30  
-    # 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+.
  28
+    #   object.expects(:expected_method)
  29
+    #   object.expected_method
  30
+    #
  31
+    # @example Expected method not invoked so error raised
31 32
     #   object = mock()
32  
-    #   object.expects(:method1 => :result1, :method2 => :result2)
  33
+    #   object.expects(:expected_method)
  34
+    #   # error raised when test completes, because expected_method not called exactly once
33 35
     #
34  
-    #   # exactly equivalent to
  36
+    # @example Expected method invoked twice so error raised
  37
+    #   object = mock()
  38
+    #   object.expects(:expected_method)
  39
+    #   object.expected_method