Permalink
Browse files

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...
1 parent 5753a8a commit 4e28497a0df59b86537cdc689ef3cd11ea6c7c3e @floehopper floehopper committed Mar 31, 2012
Showing with 1,070 additions and 663 deletions.
  1. +1 −1 COPYING.rdoc
  2. +4 −4 README.rdoc
  3. +22 −21 Rakefile
  4. +120 −106 lib/mocha/api.rb
  5. +46 −37 lib/mocha/configuration.rb
  6. +173 −77 lib/mocha/expectation.rb
  7. +84 −55 lib/mocha/mock.rb
  8. +92 −75 lib/mocha/object.rb
  9. +3 −3 lib/mocha/parameter_matchers.rb
  10. +22 −12 lib/mocha/parameter_matchers/all_of.rb
  11. +23 −12 lib/mocha/parameter_matchers/any_of.rb
  12. +15 −8 lib/mocha/parameter_matchers/any_parameters.rb
  13. +20 −11 lib/mocha/parameter_matchers/anything.rb
  14. +34 −26 lib/mocha/parameter_matchers/base.rb
  15. +23 −12 lib/mocha/parameter_matchers/equals.rb
  16. +22 −12 lib/mocha/parameter_matchers/has_entries.rb
  17. +31 −13 lib/mocha/parameter_matchers/has_entry.rb
  18. +21 −11 lib/mocha/parameter_matchers/has_key.rb
  19. +21 −11 lib/mocha/parameter_matchers/has_value.rb
  20. +14 −4 lib/mocha/parameter_matchers/includes.rb
  21. +23 −12 lib/mocha/parameter_matchers/instance_of.rb
  22. +23 −12 lib/mocha/parameter_matchers/is_a.rb
  23. +23 −12 lib/mocha/parameter_matchers/kind_of.rb
  24. +22 −12 lib/mocha/parameter_matchers/not.rb
  25. +5 −3 lib/mocha/parameter_matchers/object.rb
  26. +24 −12 lib/mocha/parameter_matchers/optionally.rb
  27. +14 −3 lib/mocha/parameter_matchers/query_string.rb
  28. +20 −10 lib/mocha/parameter_matchers/regexp_matches.rb
  29. +17 −6 lib/mocha/parameter_matchers/responds_with.rb
  30. +16 −6 lib/mocha/parameter_matchers/yaml_equivalent.rb
  31. +23 −14 lib/mocha/sequence.rb
  32. +61 −46 lib/mocha/state_machine.rb
  33. +5 −4 lib/mocha/stubbing_error.rb
  34. +3 −0 mocha.gemspec
View
@@ -1,3 +1,3 @@
Copyright Revieworld Ltd. 2006
-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].
+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}.
View
@@ -36,9 +36,9 @@ Note that versions 0.9.6 & 0.9.7 of the Rails plugin were broken. As of version
== Examples
-* Quick Start - {Usage Examples}[/examples/misc.html]
-* Traditional mocking - {Star Trek Example}[/examples/mocha.html]
-* Setting expectations on real classes - {Order Example}[/examples/stubba.html]
+* Quick Start - {file:misc.rb Usage Examples}
+* Traditional mocking - {file:mocha.rb Star Trek Example}
+* Setting expectations on real classes - {file:stubba.rb Order Example}
* More examples on {James Mead's Blog}[http://jamesmead.org/blog/]
* {Mailing List Archives}[http://groups.google.com/group/mocha-developer]
@@ -51,4 +51,4 @@ Note that versions 0.9.6 & 0.9.7 of the Rails plugin were broken. As of version
Copyright Revieworld Ltd. 2006
-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].
+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}.
View
@@ -2,7 +2,7 @@ require "bundler"
Bundler::GemHelper.install_tasks
require "bundler/setup"
-require 'rdoc/task'
+require 'yard'
require 'rake/testtask'
desc "Run all tests"
@@ -81,37 +81,38 @@ def benchmark_test_case(klass, iterations)
end
end
-desc 'Generate RDoc'
-Rake::RDocTask.new('rdoc') do |task|
- task.generator = 'hanna'
- task.main = 'README.rdoc'
- task.title = "Mocha #{Mocha::VERSION}"
- task.rdoc_dir = 'doc'
- template = File.expand_path(File.join(File.dirname(__FILE__), "templates", "html_with_google_analytics.rb"))
- if File.exist?(template)
- puts "*** Using RDoc template incorporating Google Analytics"
- task.template = template
- end
- task.rdoc_files.include(
- 'README.rdoc',
- 'RELEASE.rdoc',
- 'COPYING.rdoc',
- 'MIT-LICENSE.rdoc',
- 'agiledox.txt',
+desc 'Remove generated documentation'
+task 'clobber_yardoc' do
+ `rm -rf ./doc`
+end
+
+desc 'Generate documentation'
+YARD::Rake::YardocTask.new('yardoc') do |task|
+ task.options = ["--title", "Mocha #{Mocha::VERSION}", "--no-private"]
+ task.files = [
'lib/mocha/api.rb',
'lib/mocha/mock.rb',
'lib/mocha/expectation.rb',
'lib/mocha/object.rb',
'lib/mocha/parameter_matchers.rb',
'lib/mocha/parameter_matchers',
'lib/mocha/state_machine.rb',
+ 'lib/mocha/sequence.rb',
'lib/mocha/configuration.rb',
- 'lib/mocha/stubbing_error.rb'
- )
+ 'lib/mocha/stubbing_error.rb',
+ '-',
+ 'RELEASE.rdoc',
+ 'COPYING.rdoc',
+ 'MIT-LICENSE.rdoc',
+ 'agiledox.txt',
+ 'examples/mocha.rb',
+ 'examples/stubba.rb',
+ 'examples/misc.rb',
+ ]
end
desc "Generate documentation"
-task 'generate_docs' => ['clobber_rdoc', 'rdoc', 'examples', 'agiledox.txt']
+task 'generate_docs' => ['clobber_yardoc', 'agiledox.txt', 'yardoc']
desc "Publish docs to Github (relies on running 'generate_docs' task and committing changes to master branch)"
task 'publish_docs' do
View
@@ -2,40 +2,40 @@
require 'mocha/mockery'
require 'mocha/sequence'
-module Mocha # :nodoc:
-
- # Methods added to Test::Unit::TestCase or equivalent.
+module Mocha
+
+ # Methods added to +Test::Unit::TestCase+ or equivalent.
module API
-
+
include ParameterMatchers
-
- # :call-seq: mock(name, &block) -> mock object
- # mock(expected_methods = {}, &block) -> mock object
- # mock(name, expected_methods = {}, &block) -> mock object
- #
- # Creates a mock object.
- #
- # +name+ is a +String+ identifier for the mock object.
- #
- # +expected_methods+ is a +Hash+ with expected method name symbols as keys and corresponding return values as values.
- #
- # Note that (contrary to expectations set up by #stub) these expectations <b>must</b> be fulfilled during the test.
- # def test_product
- # product = mock('ipod_product', :manufacturer => 'ipod', :price => 100)
- # assert_equal 'ipod', product.manufacturer
- # assert_equal 100, product.price
- # # an error will be raised unless both Product#manufacturer and Product#price have been called
- # end
- #
- # +block+ is an optional block to be evaluated against the mock object instance, giving an alernative way to set up expectations & stubs.
- # def test_product
- # product = mock('ipod_product') do
- # expects(:manufacturer).returns('ipod')
- # expects(:price).returns(100)
+
+ # Builds a new mock object
+ #
+ # @param [String] name identifies mock object in error messages.
+ # @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.
+ # @yield optional block to be evaluated against the mock object instance, giving an alternative way to setup expectations.
+ # @return [Mock] a new mock object
+ #
+ # @overload def mock(name, &block)
+ # @overload def mock(expected_methods_vs_return_values = {}, &block)
+ # @overload def mock(name, expected_methods_vs_return_values = {}, &block)
+ #
+ # @example Using expected_methods_vs_return_values Hash to setup expectations.
+ # def test_motor_starts_and_stops
+ # motor = mock('motor', :start => true, :stop => true)
+ # assert motor.start
+ # assert motor.stop
+ # # an error will be raised unless both Motor#start and Motor#stop have been called
+ # end
+ # @example Using the optional block to setup expectations & stubbed methods.
+ # def test_motor_starts_and_stops
+ # motor = mock('motor') do
+ # expects(:start).with(100.rpm).returns(true)
+ # stubs(:stop).returns(true)
# end
- # assert_equal 'ipod', product.manufacturer
- # assert_equal 100, product.price
- # # an error will be raised unless both Product#manufacturer and Product#price have been called
+ # assert motor.start(100.rpm)
+ # assert motor.stop
+ # # an error will only be raised if Motor#start(100.rpm) has not been called
# end
def mock(*arguments, &block)
name = arguments.shift if arguments.first.is_a?(String)
@@ -44,58 +44,61 @@ def mock(*arguments, &block)
mock.expects(expectations)
mock
end
-
- # :call-seq: stub(name, &block) -> mock object
- # stub(stubbed_methods = {}, &block) -> mock object
- # stub(name, stubbed_methods = {}, &block) -> mock object
- #
- # Creates a mock object.
- #
- # +name+ is a +String+ identifier for the mock object.
- #
- # +stubbed_methods+ is a +Hash+ with stubbed method name symbols as keys and corresponding return values as values.
- # Note that (contrary to expectations set up by #mock) these expectations <b>need not</b> be fulfilled during the test.
- # def test_product
- # product = stub('ipod_product', :manufacturer => 'ipod', :price => 100)
- # assert_equal 'ipod', product.manufacturer
- # assert_equal 100, product.price
- # # an error will not be raised even if Product#manufacturer and Product#price have not been called
+
+ # Builds a new mock object
+ #
+ # @param [String] name identifies mock object in error messages.
+ # @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.
+ # @yield optional block to be evaluated against the mock object instance, giving an alternative way to setup stubbed methods.
+ # @return [Mock] a new mock object
+ #
+ # @overload def stub(name, &block)
+ # @overload def stub(stubbed_methods_vs_return_values = {}, &block)
+ # @overload def stub(name, stubbed_methods_vs_return_values = {}, &block)
+ #
+ # @example Using stubbed_methods_vs_return_values Hash to setup stubbed methods.
+ # def test_motor_starts_and_stops
+ # motor = mock('motor', :start => true, :stop => true)
+ # assert motor.start
+ # assert motor.stop
+ # # an error will not be raised even if either Motor#start or Motor#stop has not been called
# end
#
- # +block+ is an optional block to be evaluated against the mock object instance, giving an alernative way to set up expectations & stubs.
- # def test_product
- # product = stub('ipod_product') do
- # stubs(:manufacturer).returns('ipod')
- # stubs(:price).returns(100)
+ # @example Using the optional block to setup expectations & stubbed methods.
+ # def test_motor_starts_and_stops
+ # motor = mock('motor') do
+ # expects(:start).with(100.rpm).returns(true)
+ # stubs(:stop).returns(true)
# end
- # assert_equal 'ipod', product.manufacturer
- # assert_equal 100, product.price
- # # an error will not be raised even if Product#manufacturer and Product#price have not been called
- # end
+ # assert motor.start(100.rpm)
+ # assert motor.stop
+ # # an error will only be raised if Motor#start(100.rpm) has not been called
+ # end
def stub(*arguments, &block)
name = arguments.shift if arguments.first.is_a?(String)
expectations = arguments.shift || {}
stub = name ? Mockery.instance.named_mock(name, &block) : Mockery.instance.unnamed_mock(&block)
stub.stubs(expectations)
stub
end
-
- # :call-seq: stub_everything(name, &block) -> mock object
- # stub_everything(stubbed_methods = {}, &block) -> mock object
- # stub_everything(name, stubbed_methods = {}, &block) -> mock object
- #
- # Creates a mock object that accepts calls to any method.
- #
- # By default it will return +nil+ for any method call.
- #
- # +block+ is a block to be evaluated against the mock object instance, giving an alernative way to set up expectations & stubs.
- #
- # +name+ and +stubbed_methods+ work in the same way as for #stub.
- # def test_product
- # product = stub_everything('ipod_product', :price => 100)
- # assert_nil product.manufacturer
- # assert_nil product.any_old_method
- # assert_equal 100, product.price
+
+ # Builds a mock object that accepts calls to any method. By default it will return +nil+ for any method call.
+ #
+ # @param [String] name identifies mock object in error messages.
+ # @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.
+ # @yield optional block to be evaluated against the mock object instance, giving an alternative way to setup stubbed methods.
+ # @return [Mock] a new mock object
+ #
+ # @overload def stub_everything(name, &block)
+ # @overload def stub_everything(stubbed_methods_vs_return_values = {}, &block)
+ # @overload def stub_everything(name, stubbed_methods_vs_return_values = {}, &block)
+ #
+ # @example Ignore invocations of irrelevant methods.
+ # def test_motor_stops
+ # motor = stub_everything('motor', :stop => true)
+ # assert_nil motor.irrelevant_method_1 # => no error raised
+ # assert_nil motor.irrelevant_method_2 # => no error raised
+ # assert motor.stop
# end
def stub_everything(*arguments, &block)
name = arguments.shift if arguments.first.is_a?(String)
@@ -105,69 +108,80 @@ def stub_everything(*arguments, &block)
stub.stubs(expectations)
stub
end
-
- # :call-seq: sequence(name) -> sequence
+
+ # Builds a new sequence which can be used to constrain the order in which expectations can occur.
#
- # Returns a new sequence that is used to constrain the order in which expectations can occur.
+ # Specify that an expected invocation must occur within a named {Sequence} by using {Expectation#in_sequence}.
#
- # Specify that an expected invocation must occur in within a named +sequence+ by using Expectation#in_sequence.
+ # @return [Sequence] a new sequence
#
- # See also Expectation#in_sequence.
+ # @see Expectation#in_sequence
+ #
+ # @example Ensure methods on egg are invoked in correct order.
# breakfast = sequence('breakfast')
#
- # egg = mock('egg')
- # egg.expects(:crack).in_sequence(breakfast)
- # egg.expects(:fry).in_sequence(breakfast)
- # egg.expects(:eat).in_sequence(breakfast)
+ # egg = mock('egg') do
+ # expects(:crack).in_sequence(breakfast)
+ # expects(:fry).in_sequence(breakfast)
+ # expects(:eat).in_sequence(breakfast)
+ # end
def sequence(name)
Sequence.new(name)
end
-
- # :call-seq: states(name) -> state_machine
+
+ # Builds a new state machine which can be used to constrain the order in which expectations can occur.
#
- # Returns a new +state_machine+ that is used to constrain the order in which expectations can occur.
+ # Specify the initial state of the state machine by using {StateMachine#starts_as}.
#
- # Specify the initial +state+ of the +state_machine+ by using StateMachine#starts_as.
+ # Specify that an expected invocation should change the state of the state machine by using {Expectation#then}.
#
- # Specify that an expected invocation should change the +state+ of the +state_machine+ by using Expectation#then.
+ # Specify that an expected invocation should be constrained to occur within a particular +state+ by using {Expectation#when}.
#
- # Specify that an expected invocation should be constrained to occur within a particular +state+ by using Expectation#when.
+ # A test can contain multiple state machines.
#
- # A test can contain multiple +state_machines+.
+ # @return [StateMachine] a new state machine
#
- # See also Expectation#then, Expectation#when and StateMachine.
+ # @see Expectation#then
+ # @see Expectation#when
+ # @see StateMachine
+ # @example Constrain expected invocations to occur in particular states.
# power = states('power').starts_as('off')
#
- # radio = mock('radio')
- # radio.expects(:switch_on).then(power.is('on'))
- # radio.expects(:select_channel).with('BBC Radio 4').when(power.is('on'))
- # radio.expects(:adjust_volume).with(+5).when(power.is('on'))
- # radio.expects(:select_channel).with('BBC World Service').when(power.is('on'))
- # radio.expects(:adjust_volume).with(-5).when(power.is('on'))
- # radio.expects(:switch_off).then(power.is('off'))
+ # radio = mock('radio') do
+ # expects(:switch_on).then(power.is('on'))
+ # expects(:select_channel).with('BBC Radio 4').when(power.is('on'))
+ # expects(:adjust_volume).with(+5).when(power.is('on'))
+ # expects(:select_channel).with('BBC World Service').when(power.is('on'))
+ # expects(:adjust_volume).with(-5).when(power.is('on'))
+ # expects(:switch_off).then(power.is('off'))
+ # end
def states(name)
Mockery.instance.new_state_machine(name)
end
-
- def mocha_setup # :nodoc:
+
+ # @private
+ def mocha_setup
end
-
- def mocha_verify(assertion_counter = nil) # :nodoc:
+
+ # @private
+ def mocha_verify(assertion_counter = nil)
Mockery.instance.verify(assertion_counter)
end
-
- def mocha_teardown # :nodoc:
+
+ # @private
+ def mocha_teardown
Mockery.instance.teardown
Mockery.reset_instance
end
-
+
end
-
+
+ # @private
def self.const_missing(name)
return super unless name == :Standalone
require 'mocha/deprecation'
Deprecation.warning "Mocha::Standalone has been renamed to Mocha::API"
return API
end
-
+
end
Oops, something went wrong.

0 comments on commit 4e28497

Please sign in to comment.