Merge pull request #622 from rspec/address-yard-warnings

Address YARD warnings.

lib/rspec/mocks.rb

@@ -62,7 +62,7 @@ def self.teardown
     #                added.
     # @param opts a hash of options, :expected_from is used to set the
     #             original call site
-    # @param block an optional implementation for the allowance
+    # @yield an optional implementation for the allowance
     #
     # @example Defines the implementation of `foo` on `bar`, using the passed block
     #   x = 0
@@ -80,7 +80,7 @@ def self.allow_message(subject, message, opts={}, &block)
     #                expected.
     # @param opts a hash of options, :expected_from is used to set the
     #             original call site
-    # @param block an optional implementation for the expectation
+    # @yield an optional implementation for the expectation
     #
     # @example Expect the message `foo` to receive `bar`, then call it
     #   RSpec::Mocks.expect_message(bar, :foo)
@@ -105,7 +105,10 @@ def self.with_temporary_scope
       end
     end
 
-    class << self; attr_reader :space; end
+    class << self
+      # @private
+      attr_reader :space
+    end
     @space_stack = []
     @root_space  = @space = RSpec::Mocks::RootSpace.new
 

lib/rspec/mocks/example_methods.rb

@@ -11,11 +11,12 @@ module ExampleMethods
 
       # @overload double()
       # @overload double(name)
+      #   @param name [String/Symbol] used to clarify intent
       # @overload double(stubs)
+      #   @param stubs (Hash) hash of message/return-value pairs
       # @overload double(name, stubs)
-      # @param name [String/Symbol] (optional) used to
-      #   clarify intent
-      # @param stubs (Hash) (optional) hash of message/return-value pairs
+      #   @param name [String/Symbol] used to clarify intent
+      #   @param stubs (Hash) hash of message/return-value pairs
       # @return (Double)
       #
       # Constructs an instance of [RSpec::Mocks::Double](RSpec::Mocks::Double) configured
@@ -36,9 +37,10 @@ def double(*args)
       end
 
       # @overload instance_double(doubled_class)
+      #   @param doubled_class [String, Class]
       # @overload instance_double(doubled_class, stubs)
-      # @param doubled_class [String, Class]
-      # @param stubs [Hash] (optional) hash of message/return-value pairs
+      #   @param doubled_class [String, Class]
+      #   @param stubs [Hash] hash of message/return-value pairs
       # @return InstanceVerifyingDouble
       #
       # Constructs a test double against a specific class. If the given class
@@ -51,9 +53,10 @@ def instance_double(doubled_class, *args)
       end
 
       # @overload class_double(doubled_class)
+      #   @param doubled_class [String, Module]
       # @overload class_double(doubled_class, stubs)
-      # @param doubled_class [String, Module]
-      # @param stubs [Hash] (optional) hash of message/return-value pairs
+      #   @param doubled_class [String, Module]
+      #   @param stubs [Hash] hash of message/return-value pairs
       # @return ClassVerifyingDouble
       #
       # Constructs a test double against a specific class. If the given class
@@ -66,9 +69,10 @@ def class_double(doubled_class, *args)
       end
 
       # @overload object_double(object_or_name)
+      #   @param object_or_name [String, Object]
       # @overload object_double(object_or_name, stubs)
-      # @param object_or_name [String, Object]
-      # @param stubs [Hash] (optional) hash of message/return-value pairs
+      #   @param object_or_name [String, Object]
+      #   @param stubs [Hash] hash of message/return-value pairs
       # @return ObjectVerifyingDouble
       #
       # Constructs a test double against a specific object. Only the methods

lib/rspec/mocks/syntax.rb

@@ -201,109 +201,130 @@ def self.default_should_syntax_host
 
         ::BasicObject
       end
-
-      # @method should_receive
-      # Sets an expectation that this object should receive a message before
-      # the end of the example.
-      #
-      # @example
-      #
-      #     logger = double('logger')
-      #     thing_that_logs = ThingThatLogs.new(logger)
-      #     logger.should_receive(:log)
-      #     thing_that_logs.do_something_that_logs_a_message
-      #
-      # @note This is only available when you have enabled the `should` syntax.
-
-      # @method should_not_receive
-      # Sets and expectation that this object should _not_ receive a message
-      # during this example.
-
-      # @method stub
-      # Tells the object to respond to the message with the specified value.
-      #
-      # @example
-      #
-      #     counter.stub(:count).and_return(37)
-      #     counter.stub(:count => 37)
-      #     counter.stub(:count) { 37 }
-      #
-      # @note This is only available when you have enabled the `should` syntax.
-
-      # @method unstub
-      # Removes a stub. On a double, the object will no longer respond to
-      # `message`. On a real object, the original method (if it exists) is
-      # restored.
-      #
-      # This is rarely used, but can be useful when a stub is set up during a
-      # shared `before` hook for the common case, but you want to replace it
-      # for a special case.
-      #
-      # @note This is only available when you have enabled the `should` syntax.
-
-      # @method stub_chain
-      # @overload stub_chain(method1, method2)
-      # @overload stub_chain("method1.method2")
-      # @overload stub_chain(method1, method_to_value_hash)
-      #
-      # Stubs a chain of methods.
-      #
-      # ## Warning:
-      #
-      # Chains can be arbitrarily long, which makes it quite painless to
-      # violate the Law of Demeter in violent ways, so you should consider any
-      # use of `stub_chain` a code smell. Even though not all code smells
-      # indicate real problems (think fluent interfaces), `stub_chain` still
-      # results in brittle examples.  For example, if you write
-      # `foo.stub_chain(:bar, :baz => 37)` in a spec and then the
-      # implementation calls `foo.baz.bar`, the stub will not work.
-      #
-      # @example
-      #
-      #     double.stub_chain("foo.bar") { :baz }
-      #     double.stub_chain(:foo, :bar => :baz)
-      #     double.stub_chain(:foo, :bar) { :baz }
-      #
-      #     # Given any of ^^ these three forms ^^:
-      #     double.foo.bar # => :baz
-      #
-      #     # Common use in Rails/ActiveRecord:
-      #     Article.stub_chain("recent.published") { [Article.new] }
-      #
-      # @note This is only available when you have enabled the `should` syntax.
-
-      # @method as_null_object
-      # Tells the object to respond to all messages. If specific stub values
-      # are declared, they'll work as expected. If not, the receiver is
-      # returned.
-      #
-      # @note This is only available when you have enabled the `should` syntax.
-
-      # @method null_object?
-      # Returns true if this object has received `as_null_object`
-      #
-      # @note This is only available when you have enabled the `should` syntax.
-
-      # @method any_instance
-      # Used to set stubs and message expectations on any instance of a given
-      # class. Returns a [Recorder](Recorder), which records messages like
-      # `stub` and `should_receive` for later playback on instances of the
-      # class.
-      #
-      # @example
-      #
-      #     Car.any_instance.should_receive(:go)
-      #     race = Race.new
-      #     race.cars << Car.new
-      #     race.go # assuming this delegates to all of its cars
-      #             # this example would pass
-      #
-      #     Account.any_instance.stub(:balance) { Money.new(:USD, 25) }
-      #     Account.new.balance # => Money.new(:USD, 25))
-      #
-      # @return [Recorder]
-      #
-      # @note This is only available when you have enabled the `should` syntax.
     end
   end
 end
+
+# The legacy `:should` syntax adds the following methods directly to
+# `BasicObject` so that they are available off of any object. Note, however,
+# that this syntax does not always play nice with delegate/proxy objects.
+# We recommend you use the non-monkeypatching `:expect` syntax instead.
+# @see Class
+class BasicObject
+  # @method should_receive
+  # Sets an expectation that this object should receive a message before
+  # the end of the example.
+  #
+  # @example
+  #
+  #     logger = double('logger')
+  #     thing_that_logs = ThingThatLogs.new(logger)
+  #     logger.should_receive(:log)
+  #     thing_that_logs.do_something_that_logs_a_message
+  #
+  # @note This is only available when you have enabled the `should` syntax.
+  # @see RSpec::Mocks::ExampleMethods#expect
+
+  # @method should_not_receive
+  # Sets and expectation that this object should _not_ receive a message
+  # during this example.
+  # @see RSpec::Mocks::ExampleMethods#expect
+
+  # @method stub
+  # Tells the object to respond to the message with the specified value.
+  #
+  # @example
+  #
+  #     counter.stub(:count).and_return(37)
+  #     counter.stub(:count => 37)
+  #     counter.stub(:count) { 37 }
+  #
+  # @note This is only available when you have enabled the `should` syntax.
+  # @see RSpec::Mocks::ExampleMethods#allow
+
+  # @method unstub
+  # Removes a stub. On a double, the object will no longer respond to
+  # `message`. On a real object, the original method (if it exists) is
+  # restored.
+  #
+  # This is rarely used, but can be useful when a stub is set up during a
+  # shared `before` hook for the common case, but you want to replace it
+  # for a special case.
+  #
+  # @note This is only available when you have enabled the `should` syntax.
+
+  # @method stub_chain
+  # @overload stub_chain(method1, method2)
+  # @overload stub_chain("method1.method2")
+  # @overload stub_chain(method1, method_to_value_hash)
+  #
+  # Stubs a chain of methods.
+  #
+  # ## Warning:
+  #
+  # Chains can be arbitrarily long, which makes it quite painless to
+  # violate the Law of Demeter in violent ways, so you should consider any
+  # use of `stub_chain` a code smell. Even though not all code smells
+  # indicate real problems (think fluent interfaces), `stub_chain` still
+  # results in brittle examples.  For example, if you write
+  # `foo.stub_chain(:bar, :baz => 37)` in a spec and then the
+  # implementation calls `foo.baz.bar`, the stub will not work.
+  #
+  # @example
+  #
+  #     double.stub_chain("foo.bar") { :baz }
+  #     double.stub_chain(:foo, :bar => :baz)
+  #     double.stub_chain(:foo, :bar) { :baz }
+  #
+  #     # Given any of ^^ these three forms ^^:
+  #     double.foo.bar # => :baz
+  #
+  #     # Common use in Rails/ActiveRecord:
+  #     Article.stub_chain("recent.published") { [Article.new] }
+  #
+  # @note This is only available when you have enabled the `should` syntax.
+  # @see RSpec::Mocks::ExampleMethods#receive_message_chain
+
+  # @method as_null_object
+  # Tells the object to respond to all messages. If specific stub values
+  # are declared, they'll work as expected. If not, the receiver is
+  # returned.
+  #
+  # @note This is only available when you have enabled the `should` syntax.
+
+  # @method null_object?
+  # Returns true if this object has received `as_null_object`
+  #
+  # @note This is only available when you have enabled the `should` syntax.
+end
+
+# The legacy `:should` syntax adds the `any_instance` to `Class`.
+# We generally recommend you use the newer `:expect` syntax instead,
+# which allows you to stub any instance of a class using
+# `allow_any_instance_of(klass)` or mock any instance using
+# `expect_any_instance_of(klass)`.
+# @see BasicObject
+class Class
+  # @method any_instance
+  # Used to set stubs and message expectations on any instance of a given
+  # class. Returns a [Recorder](Recorder), which records messages like
+  # `stub` and `should_receive` for later playback on instances of the
+  # class.
+  #
+  # @example
+  #
+  #     Car.any_instance.should_receive(:go)
+  #     race = Race.new
+  #     race.cars << Car.new
+  #     race.go # assuming this delegates to all of its cars
+  #             # this example would pass
+  #
+  #     Account.any_instance.stub(:balance) { Money.new(:USD, 25) }
+  #     Account.new.balance # => Money.new(:USD, 25))
+  #
+  # @return [Recorder]
+  #
+  # @note This is only available when you have enabled the `should` syntax.
+  # @see RSpec::Mocks::ExampleMethods#expect_any_instance_of
+  # @see RSpec::Mocks::ExampleMethods#allow_any_instance_of
+end