Reworked MOCK_CONSTRAINT to be able to provide names to parameters

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

build/boost/doc/changelog.qbk

@@ -1,5 +1,12 @@
 [section Changelog]
 
+[section trunk]
+Not yet released
+
+* Reworked MOCK_CONSTRAINT to be able to provide names to parameters
+
+[endsect]
+
 [section 1.2.3]
 Released 20 May 2013
 

build/boost/doc/customization.qbk

@@ -99,7 +99,7 @@ See [link turtle.reference.expectation.constraints constraints] for an explanati
 
 For more information about the serialization operator and the use of mock::format, refer to [link turtle.customization.logging loggin].
 
-[note The [link turtle.reference.helpers.mock_constraint MOCK_CONSTRAINT] macro takes care of everything for simple cases.]
+[note The [link turtle.reference.constraint constraint helper macro] takes care of everything for simple cases.]
 
 [endsect]
 

build/boost/doc/example/reference.cpp

@@ -759,8 +759,8 @@ BOOST_AUTO_TEST_CASE( demonstrates_resetting_a_static_mock_method )
 namespace helpers_example_1
 {
 //[ helpers_example_1
-MOCK_CONSTRAINT( 0, any, true )               // this is (almost) how mock::any is defined
-MOCK_CONSTRAINT( 0, forty_two, actual == 42 ) // this defines a 'forty_two' constraint
+MOCK_CONSTRAINT( any, true )               // this is how mock::any could be defined
+MOCK_CONSTRAINT( forty_two, actual == 42 ) // this defines a 'forty_two' constraint
 
 BOOST_AUTO_TEST_CASE( mock_constraint_0_arity )
 {
@@ -774,8 +774,8 @@ BOOST_AUTO_TEST_CASE( mock_constraint_0_arity )
 namespace helpers_example_2
 {
 //[ helpers_example_2
-MOCK_CONSTRAINT( 1, equal, actual == expected_0 )                  // this is how mock::equal is defined
-MOCK_CONSTRAINT( 1, near, std::abs( actual - expected_0 ) < 0.01 ) // this defines a 'near' constraint which can be used as 'near( 42 )'
+MOCK_CONSTRAINT( equal, expected, actual == expected )                  // this is how mock::equal could be defined
+MOCK_CONSTRAINT( near, expected, std::abs( actual - expected ) < 0.01 ) // this defines a 'near' constraint which can be used as 'near( 42 )'
 
 BOOST_AUTO_TEST_CASE( mock_constraint_1_arity )
 {
@@ -789,7 +789,50 @@ BOOST_AUTO_TEST_CASE( mock_constraint_1_arity )
 namespace helpers_example_3
 {
 //[ helpers_example_3
-MOCK_CONSTRAINT( 2, near, std::abs( actual - expected_0 ) < expected_1 ) // this is how mock::near is defined
+MOCK_CONSTRAINT( near, expected, tolerance, std::abs( actual - expected ) < tolerance ) // this is how mock::near could be defined
+
+BOOST_AUTO_TEST_CASE( mock_constraint_2_arity )
+{
+    MOCK_FUNCTOR( f, void( int ) );
+    MOCK_EXPECT( f ).with( near( 42, 0.001 ) );
+}
+//]
+}
+
+namespace helpers_example_4
+{
+//[ helpers_example_4
+MOCK_CONSTRAINT_EXT( any, 0,, true )               // this is (almost) how mock::any is defined
+MOCK_CONSTRAINT_EXT( forty_two, 0,, actual == 42 ) // this defines a 'forty_two' constraint
+
+BOOST_AUTO_TEST_CASE( mock_constraint_0_arity )
+{
+    MOCK_FUNCTOR( f, void( int ) );
+    MOCK_EXPECT( f ).with( forty_two );
+    MOCK_EXPECT( f ).with( any );
+}
+//]
+}
+
+namespace helpers_example_5
+{
+//[ helpers_example_5
+MOCK_CONSTRAINT_EXT( equal, 1, ( expected ), actual == expected )                  // this is how mock::equal is defined
+MOCK_CONSTRAINT_EXT( near, 1, ( expected ), std::abs( actual - expected ) < 0.01 ) // this defines a 'near' constraint which can be used as 'near( 42 )'
+
+BOOST_AUTO_TEST_CASE( mock_constraint_1_arity )
+{
+    MOCK_FUNCTOR( f, void( int ) );
+    MOCK_EXPECT( f ).with( near( 42 ) );
+    MOCK_EXPECT( f ).with( equal( 42 ) );
+}
+//]
+}
+
+namespace helpers_example_6
+{
+//[ helpers_example_6
+MOCK_CONSTRAINT_EXT( near, 2, ( expected, tolerance ), std::abs( actual - expected ) < tolerance ) // this is how mock::near is defined
 
 BOOST_AUTO_TEST_CASE( mock_constraint_2_arity )
 {

build/boost/doc/reference.qbk

@@ -96,7 +96,7 @@ Synopsis :
 
 [note [link turtle.reference.creation.constructor Constructors], [link turtle.reference.creation.destructor destructors] and [link turtle.reference.creation.conversion_operator conversion operators] require special care.]
 
-With a compiler without support for variadic macros the signature and the identifier cannot be specified, thus in case of ambiguity another set of macros must be used.
+For compilers without support for variadic macros the signature and the identifier cannot be specified, thus in case of ambiguity another set of macros must be used.
 
 Synopsis :
  
@@ -150,7 +150,7 @@ Synopsis :
 
 [note A static object is used behind the scene in order to keep track of the expectations of a mock static method, therefore to ensure all tests run in isolation it is strongly suggested to manually [link turtle.reference.verification verify] and [link turtle.reference.reset reset] the static method at the end of each test.]
 
-[warning With a compiler without support for variadic macros the identifier cannot be ommitted and must be given explicitly.]
+[warning For compilers without support for variadic macros the identifier cannot be ommitted and must be given explicitly.]
 
 Example :
 
@@ -244,7 +244,7 @@ Synopsis :
 
 [note A static object is used behind the scene in order to keep track of the expectations of a mock function, therefore to ensure all tests run in isolation it is strongly suggested to manually [link turtle.reference.verification verify] and [link turtle.reference.reset reset] the mock function at the end of each test.]
 
-[warning With a compiler without support for variadic macros the identifier cannot be ommitted and must be given explicitly.]
+[warning For compilers without support for variadic macros the identifier cannot be ommitted and must be given explicitly.]
 
 Example :
 
@@ -308,6 +308,8 @@ Synopsis :
 
  MOCK_EXPECT( identifier ).with( constraint_1, constraint_2, ... );
 
+The number of constraints must match the number of mocked parameters.
+
 Constraints :
 
 [table
@@ -395,7 +397,7 @@ A sequence enforces a given order between two or more expectations.
 
 Synopsis :
 
- MOCK_EXPECT( identifier_1 ).in( sequence_1 [, sequence_2 [, ...]] );
+ MOCK_EXPECT( identifier_1 ).in( sequence_1, sequence_2, ... );
 
 Each sequence is an instance of mock::sequence.
 
@@ -488,33 +490,47 @@ Example :
 
 [endsect]
 
-[section Helpers]
+[section Constraint]
 
-This section presents various useful tools.
-
-[section MOCK_CONSTRAINT]
+This section presents a simple means of creating a new constraint.
 
 Synopsis :
 
- MOCK_CONSTRAINT( arity, name, expression ) // defines a constraint 'name' based on the given 'expression'
+ MOCK_CONSTRAINT( name, expected_1, expected_2, ..., expression ) // defines a constraint 'name' based on the given 'expression'
 
-The expression manipulates the received parameter ['actual] in order to implement the constraint, as well as ['arity] extra expected arguments ['expected_0], ['expected_1], etc...
+The expression manipulates a received parameter ['actual] in order to implement the constraint, as well as extra optional arguments named ['expected_1], ['expected_2], ...
 
-[note The type of all expected arguments must be copy-constructible and assignable.]
+For compilers without supporting variadic macros the alternate following macro must be used.
+
+Synopsis :
+
+ MOCK_CONSTRAINT_EXT( name, arity, ( expected_1, expected_2, ... ), expression ) // defines a constraint 'name' based on the given 'expression'
+
+Of course this macro is also available for compilers which support variadic macros.
 
 Example without any extra argument :
 
 [helpers_example_1]
 
+or with the alternate more portable macro :
+
+[helpers_example_4]
+
 Example with one extra argument :
 
 [helpers_example_2]
 
+or with the alternate more portable macro :
+
+[helpers_example_5]
+
 Example with two extra arguments :
 
 [helpers_example_3]
 
-[endsect]
+or with the alternate more portable macro :
+
+[helpers_example_6]
 
 [endsect]