Document how actions store data by copy

doc/changelog.qbk

@@ -15,6 +15,7 @@ Not yet released
 * Added inline to generated MOCK_FUNCTION
 * Documented limitation concerning MOCK_METHOD_TPL
 * Fixed mocking protected member function
+* Document how actions store data by copy
 
 [section 1.2.6]
 Released 24 May 2014

doc/example/reference.cpp

@@ -798,6 +798,25 @@ BOOST_AUTO_TEST_CASE( demonstrates_configuring_actions )
 
 #endif
 
+namespace action_example_2
+{
+//[ action_example_2
+MOCK_CLASS( mock_class )
+{
+    MOCK_METHOD( method, 0, int&() )
+};
+
+BOOST_AUTO_TEST_CASE( demonstrates_configuring_actions_with_references )
+{
+   mock_class c;
+   int i = 0;
+   MOCK_EXPECT( c.method ).returns( boost::ref( i ) ); // wrap i to store a reference
+   c.method() = 42;                                    // really change i and not just the stored copy
+   BOOST_CHECK_EQUAL( 42, i );                         // indeed
+}
+//]
+}
+
 namespace verification_example_1
 {
 //[ verification_example_1

doc/reference.qbk

@@ -488,17 +488,23 @@ An action performs additional treatments after an expectation has been deemed va
 
 Synopsis :
 
- MOCK_EXPECT( identifier ).returns( value );
+ MOCK_EXPECT( identifier ).returns( value );    // stored internally by copy
- MOCK_EXPECT( identifier ).moves( value );
+ MOCK_EXPECT( identifier ).moves( value );      // stored internally by copy
- MOCK_EXPECT( identifier ).throws( exception );
+ MOCK_EXPECT( identifier ).throws( exception ); // stored internally by copy
- MOCK_EXPECT( identifier ).calls( functor );    // gets assigned to a boost::function and throws std::invalid_argument if empty
+ MOCK_EXPECT( identifier ).calls( functor );    // stored internally by copy, throws std::invalid_argument if empty
 
 [note The returns and moves actions are not available for mock methods returning void, including constructors and destructors.]
 
+[note Actions are captured by copy, boost::ref and boost::cref can however be used to turn the copies into references.]
+
 Example :
 
 [action_example_1]
 
+Example with references :
+
+[action_example_2]
+
 [endsect]
 
 [endsect]