Document multiple calls with allow_any_instance_of (#1510)

* Document multiple values with allow_any_instance_of

features/configuring_responses/returning_a_value.feature

@@ -4,6 +4,12 @@ Feature: Returning a value
   different return values for consecutive calls. The final value will continue to be returned if
   the message is received additional times.
 
+  Note - using the multiple calls feature with `allow_any_instance_of` can result in confusing
+  behavior.  The rspec-mocks team [discourages](../../working_with_legacy_code/any_instance.feature)
+  using `allow_any_instance_of`, but its interaction with `and_return` is documented in
+  the [Working with Legacy Code](../../working_with_legacy_code/any_instance.feature#specify-different-return-values-for-multiple-calls-in-combination-with-`allow-any-instance-of`)
+  section.
+
   Scenario: Nil is returned by default
     Given a file named "returns_nil_spec.rb" with:
       """ruby
@@ -43,7 +49,7 @@ Feature: Returning a value
           expect(dbl.foo).to eq(1)
           expect(dbl.foo).to eq(2)
           expect(dbl.foo).to eq(3)
-          expect(dbl.foo).to eq(3)
+          expect(dbl.foo).to eq(3) # begins to repeat last value
           expect(dbl.foo).to eq(3)
         end
       end

features/working_with_legacy_code/any_instance.feature

@@ -115,3 +115,44 @@ Feature: Any Instance
     Then it should fail with the following output:
       | 2 examples, 1 failure |
       | Exactly one instance should have received the following message(s) but didn't: foo |
+
+  Scenario: Specify different return values for multiple calls in combination with allow_any_instance_of
+
+    Using the multiple calls feature with `allow_any_instance_of` can result in confusing behavior.  With
+    `allow_any_instance_of`, the multiple calls are *configured* on the class, but *tracked* on the instance.  Therefore,
+    each individual instance will return the configured return values in the order specified, and then begin to repeat
+    the last value, as demonstrated in this code:
+
+    Given a file named "multiple_calls_spec_with_allow_any_instance_of.rb" with:
+      """ruby
+      class SomeClass
+      end
+
+      RSpec.describe "When the method is called multiple times on different instances with allow_any_instance_of" do
+        it "demonstrates the mocked behavior on each instance individually" do
+          allow_any_instance_of(SomeClass).to receive(:foo).and_return(1, 2, 3)
+
+          first = SomeClass.new
+          second = SomeClass.new
+          third = SomeClass.new
+
+          expect(first.foo).to eq(1)
+          expect(second.foo).to eq(1)
+
+          expect(first.foo).to eq(2)
+          expect(second.foo).to eq(2)
+
+          expect(first.foo).to eq(3)
+          expect(first.foo).to eq(3) # begins to repeat last value
+          expect(second.foo).to eq(3)
+          expect(second.foo).to eq(3) # begins to repeat last value
+
+          expect(third.foo).to eq(1)
+          expect(third.foo).to eq(2)
+          expect(third.foo).to eq(3)
+          expect(third.foo).to eq(3) # begins to repeat last value
+        end
+      end
+      """
+    When I run `rspec multiple_calls_spec_with_allow_any_instance_of.rb`
+    Then the examples should all pass