Updated documentation

git-svn-id: https://svn.code.sf.net/p/turtle/code/trunk@579 860be788-9bd5-4423-9f1e-828f051e677b

build/boost/doc/Jamfile.jam

@@ -47,3 +47,6 @@ project example
 compile example/motivation.cpp ;
 compile example/getting_started.cpp ;
 compile example/customisation.cpp ;
+compile example/async_call.cpp ;
+compile example/retrieve_cref.cpp ;
+compile example/invoke_functor.cpp ;

build/boost/doc/example/async_call.cpp

@@ -0,0 +1,53 @@
+//[ async_call_problem
+namespace
+{
+    class base_class
+    {
+    public:
+        virtual void method() = 0;
+    };
+
+    class my_class
+    {
+    public:
+        explicit my_class( base_class& );
+
+        void flush(); // repetitively calling this method will in turn call base_class::method at some point
+    };
+}
+//]
+
+//[ async_call_solution
+#define BOOST_AUTO_TEST_MAIN
+#include <boost/test/auto_unit_test.hpp>
+#include <boost/lambda/lambda.hpp>
+#include <boost/thread.hpp>
+#include <turtle/mock.hpp>
+
+namespace
+{
+    template< typename F >
+    void wait( bool& condition, F flush, int timeout = 100, int sleep = 100 )
+    {
+        while( !condition && timeout > 0 )
+        {
+            --timeout;
+            boost::this_thread::sleep( boost::posix_time::milliseconds( sleep ) );
+            flush();
+        }
+    }
+    MOCK_BASE_CLASS( mock_base_class, base_class )
+    {
+        MOCK_METHOD( method, 0 )
+    };
+}
+
+BOOST_AUTO_TEST_CASE( method_is_called )
+{
+    mock_base_class mock;
+    my_class c( mock );
+    bool done = false;
+    MOCK_EXPECT( mock.method ).once().calls( boost::lambda::var( done ) = true ); // when method is called it will set done to true
+    wait( done, boost::bind( &my_class::flush, &c ) );                            // just wait on done flushing from time to time
+}
+//]

build/boost/doc/example/invoke_functor.cpp

@@ -0,0 +1,36 @@
+//[ invoke_functor_problem
+#include <boost/function.hpp>
+
+namespace
+{
+    class base_class
+    {
+    public:
+        virtual void method( boost::function< void( int ) > functor ) = 0;
+    };
+
+    void function( base_class& ); // the function will call 'method' with a functor to be applied
+}
+//]
+
+//[ invoke_functor_solution
+#define BOOST_AUTO_TEST_MAIN
+#include <boost/test/auto_unit_test.hpp>
+#include <boost/bind/apply.hpp>
+#include <turtle/mock.hpp>
+
+namespace
+{
+    MOCK_BASE_CLASS( mock_class, base_class )
+    {
+        MOCK_METHOD( method, 1 )
+    };
+}
+
+BOOST_AUTO_TEST_CASE( how_to_invoke_a_functor_passed_as_parameter_of_a_mock_method )
+{
+    mock_class mock;
+    MOCK_EXPECT( mock.method ).calls( boost::bind( boost::apply< void >(), _1, 42 ) ); // whenever 'method' is called, invoke the functor with 42
+    function( mock );
+}
+//]

build/boost/doc/example/retrieve_cref.cpp

@@ -0,0 +1,42 @@
+//[ retrieve_cref_problem
+namespace
+{
+    class base_class
+    {
+    public:
+        virtual void method( int value ) = 0;
+    };
+
+    class my_class
+    {
+    public:
+        explicit my_class( base_class& );
+
+        void process(); // the processing will call 'method' two times with the same value, but we don't know what value beforehand
+    };
+}
+//]
+
+//[ retrieve_cref_solution
+#define BOOST_AUTO_TEST_MAIN
+#include <boost/test/auto_unit_test.hpp>
+#include <turtle/mock.hpp>
+
+namespace
+{
+    MOCK_BASE_CLASS( mock_base_class, base_class )
+    {
+        MOCK_METHOD( method, 1 )
+    };
+}
+
+BOOST_AUTO_TEST_CASE( method_is_called_two_times_with_the_same_value )
+{
+    mock_base_class mock;
+    my_class c( mock );
+    int value;
+    MOCK_EXPECT( mock.method ).once().with( mock::retrieve( value ) ); // on first call retrieve the value, this expectation takes precedence because it can never fail
+    MOCK_EXPECT( mock.method ).once().with( boost::cref( value ) );    // on second call compare the previously retrieved value with the newly received one
+    c.process();
+}
+//]

build/boost/doc/patterns.qbk

@@ -1,4 +1,7 @@
 [section Patterns]
+[import example/async_call.cpp]
+[import example/retrieve_cref.cpp]
+[import example/invoke_functor.cpp]
 
 This section highlights not-so-obvious features of the library gathered from real use cases.
 
@@ -6,55 +9,11 @@ This section highlights not-so-obvious features of the library gathered from rea
 
 Problem :
 
- namespace
+[async_call_problem]
- {
-     class base_class
-     {
-     public:
-         virtual void method() = 0;
-     };
- 
-     class my_class
-     {
-     public:
-         explicit my_class( base_class& );
- 
-         void flush(); // repetitively calling this method will in turn call base_class::method at some point
-     };
- }
 
 Solution :
 
- #include <turtle/mock.hpp>
+[async_call_solution]
- #include <boost/lambda/lambda.hpp>
- #include <boost/thread.hpp>
- 
- namespace
- {
-     template< typename F >
-     void wait( bool& condition, F flush, int timeout = 100, int sleep = 100 )
-     {
-         while( !condition && timeout > 0 )
-         {
-             --timeout;
-             boost::this_thread::sleep( boost::posix_time::milliseconds( sleep ) );
-             flush();
-         }
-     }
-     MOCK_BASE_CLASS( mock_base_class, base_class )
-     {
-         MOCK_METHOD( method, 0 )
-     };
- }
- 
- BOOST_AUTO_TEST_CASE( method_is_called )
- {
-     mock_base_class mock;
-     my_class c( mock );
-     bool done = false;
-     MOCK_EXPECT( mock.method ).once().calls( boost::lambda::var( done ) = true ); // when method is called it will set done to true
-     wait( done, boost::bind( &my_class::flush, &c ) );                            // just wait on done flushing from time to time
- }
 
 [endsect]
 
@@ -62,70 +21,23 @@ Solution :
 
 Problem :
 
- namespace
+[retrieve_cref_problem]
- {
-     class base_class
-     {
-     public:
-         virtual void method( int value ) = 0;
-     };
- 
-     class my_class
-     {
-     public:
-         explicit my_class( base_class& );
- 
-         void process(); // the processing will call 'method' two times with the same value, but we don't know what value beforehand
-     };
- }
 
 Solution :
 
- #include <turtle/mock.hpp>
+[retrieve_cref_solution]
- 
- namespace
- {
-     MOCK_BASE_CLASS( mock_base_class, base_class )
-     {
-         MOCK_METHOD( method, 1 )
-     };
- }
- 
- BOOST_AUTO_TEST_CASE( method_is_called_two_times_with_the_same_value )
- {
-     mock_base_class mock;
-     my_class c( mock );
-     int value;
-     MOCK_EXPECT( mock.method ).once().with( mock::retrieve( value ) ); // on first call retrieve the value, this expectation takes precedence because it can never fail
-     MOCK_EXPECT( mock.method ).once().with( boost::cref( value ) );    // on second call compare the previously retrieved value with the newly received one
-     c.process();
- }
 
 [endsect]
 
 [section Invoking a functor received as parameter]
 
- #include <turtle/mock.hpp>
+Problem :
- #include <boost/function.hpp>
+
- #include <boost/bind/apply.hpp>
+[invoke_functor_problem]
- #include <boost/bind.hpp>
+
- 
+Solution :
- namespace
+
- {
+[invoke_functor_solution]
-     MOCK_CLASS( mock_class )
-     {
-         MOCK_METHOD_EXT( method, 1, void( boost::function< void( int ) > ), method )
-     };
- }
- 
- BOOST_AUTO_TEST_CASE( how_to_invoke_a_functor_passed_as_parameter_of_a_mock_method )
- {
-     mock_class mock;
-     MOCK_EXPECT( mock.method ).calls( boost::bind( boost::apply< void >(), _1, 42 ) ); // whenever 'method' is called, invoke the functor with 42
-     MOCK_FUNCTOR( f, void( int ) );                                                    // create a mock functor to verify this
-     MOCK_EXPECT( f ).once().with( 42 );                                                // expect it to be called with 42
-     mock.method( f );                                                                  // call 'method' with the mock functor
- }
 
 [endsect]