Merge pull request #700 from freerange/improvements-to-docs-for-cardi…

…nality-related-methods

Improvements to docs for cardinality related methods

lib/mocha/expectation.rb

@@ -17,12 +17,12 @@
 module Mocha
   # Methods on expectations returned from {Mock#expects}, {Mock#stubs}, {ObjectMethods#expects} and {ObjectMethods#stubs}.
   class Expectation
-    # Modifies expectation so that the number of calls to the expected method must be within a specific +range+.
+    # Modifies expectation so that the number of invocations of the expected method must be within a specified range or exactly equal to a specified number.
     #
-    # @param [Range,Integer] range specifies the allowable range in the number of expected invocations.
+    # @param [Range,Integer] range_or_number specifies the allowable range for the number of expected invocations or the specified 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.
+    # @example Specifying an exact number of expected invocations.
     #   object = mock()
     #   object.expects(:expected_method).times(3)
     #   3.times { object.expected_method }
@@ -33,7 +33,7 @@ class Expectation
     #   2.times { object.expected_method }
     #   # => verify fails
     #
-    # @example Specifying a range in the number of expected invocations.
+    # @example Specifying a range for the number of expected invocations.
     #   object = mock()
     #   object.expects(:expected_method).times(2..4)
     #   3.times { object.expected_method }
@@ -43,12 +43,12 @@ class Expectation
     #   object.expects(:expected_method).times(2..4)
     #   object.expected_method
     #   # => verify fails
-    def times(range)
-      @cardinality.times(range)
+    def times(range_or_number)
+      @cardinality.times(range_or_number)
       self
     end
 
-    # Modifies expectation so that the expected method must be called exactly twice.
+    # Modifies expectation so that the expected method must be called exactly twice. This is equivalent to calling {#times} with an argument of +2+.
     #
     # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
     #
@@ -74,7 +74,7 @@ def twice
       self
     end
 
-    # Modifies expectation so that the expected method must be called exactly once.
+    # Modifies expectation so that the expected method must be called exactly once. This is equivalent to calling {#times} with an argument of +1+.
     #
     # Note that this is the default behaviour for an expectation, but you may wish to use it for clarity/emphasis.
     #
@@ -136,7 +136,7 @@ def at_least(minimum_number_of_times)
       self
     end
 
-    # Modifies expectation so that the expected method must be called at least once.
+    # Modifies expectation so that the expected method must be called at least once. This is equivalent to calling {#at_least} with an argument of +1+.
     #
     # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
     #
@@ -172,7 +172,7 @@ def at_most(maximum_number_of_times)
       self
     end
 
-    # Modifies expectation so that the expected method must be called at most once.
+    # Modifies expectation so that the expected method must be called at most once. This is equivalent to calling {#at_most} with an argument of +1+.
     #
     # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
     #