Updated documentation

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

build/boost/doc/example/reference.cpp

@@ -138,7 +138,7 @@ struct base_class
 
 MOCK_BASE_CLASS( mock_class, base_class )
 {
-    MOCK_METHOD( method, 2, void( int, const std::string& ), identifier_1 ) // MOCK_METHOD cannot be used because of overloading
+    MOCK_METHOD( method, 2, void( int, const std::string& ), identifier_1 ) // both the signature and identifier must be specified because of ambiguity due to overloading
     MOCK_METHOD( method, 1, void( float ), identifier_2 )                   // the identifier must differ from the previous one in order to fully disambiguate methods
 };
 //]

build/boost/doc/limitations.qbk

@@ -104,45 +104,6 @@ The workaround would be to add the signature to MOCK_METHOD :
 
 [endsect]
 
-[section Compilers without support for variadic macros cannot rely solely on MOCK_METHOD]
-
- MOCK_CLASS( my_mock )
- {
-     MOCK_METHOD( method_1, 0, void() )           // this fails to compile with compilers without variadic macros
-     MOCK_METHOD( method_2, 0, void(), method_2 ) // this too fails with compilers without variadic macros
- };
-
-The workaround would be to use the MOCK_METHOD_EXT macro :
-
- MOCK_CLASS( my_mock )
- {
-     MOCK_METHOD_EXT( method_1, 0, void(), method_1 ) // the last argument must be specified
-     MOCK_METHOD_EXT( method_2, 0, void(), method_2 )
- };
-
-The last 'identifier' argument must also always be specified for all other macros.
-
-Synopsis :
- 
- MOCK_METHOD_EXT( name, arity, signature, identifier )               // generates both const and non-const methods, compatible with compilers not supporting variadic macros
- MOCK_CONST_METHOD_EXT( name, arity, signature, identifier )         // generates only the const version of the method, for compilers not supporting variadic macros
- MOCK_NON_CONST_METHOD_EXT( name, arity, signature, identifier )     // generates only the non-const version of the method, for compilers not supporting variadic macros
- 
- MOCK_METHOD_EXT_TPL( name, arity, signature, identifier )           // must be used if the signature uses a template parameter of the class, for compilers not supporting variadic macros
- MOCK_CONST_METHOD_EXT_TPL( name, arity, signature, identifier )     // must be used if the signature uses a template parameter of the class, for compilers not supporting variadic macros
- MOCK_NON_CONST_METHOD_EXT_TPL( name, arity, signature, identifier ) // must be used if the signature uses a template parameter of the class, for compilers not supporting variadic macros
- 
- MOCK_STATIC_METHOD( name, arity, signature, identifier )
- MOCK_STATIC_METHOD_TPL( name, arity, signature, identifier )        // must be used if the signature uses a template parameter of the class, 'identifier' cannot be omitted, for compilers not supporting variadic macros
- 
- MOCK_FUNCTION( name, arity, signature, identifier )                 // 'identifier' cannot be omitted, for compilers not supporting variadic macros
-
-The other parts of the user interface remain unchanged.
-
-Of course those macros are also available for compilers which support variadic macros.
-
-[endsect]
-
 [section Compilers without support for variadic macros fail on commas in MOCK_BASE_CLASS]
 
 For compilers without support for variadic macros the following code does not compile :

build/boost/doc/reference.qbk

@@ -80,18 +80,35 @@ Deriving from mock::object is optional but provides the additional following ben
 
 Synopsis :
 
- MOCK_METHOD( name, arity )                                        // generates both const and non-const methods, only works in the context of a derived MOCK_BASE_CLASS or base_type typedef
+ MOCK_METHOD( name, arity[, signature[, identifier]] )               // generates both const and non-const methods
- MOCK_METHOD( name, arity, signature[, identifier] )               // generates both const and non-const methods, if 'identifier' is omitted it will default to 'name'
+ MOCK_CONST_METHOD( name, arity[, signature[, identifier]] )         // generates only the const version of the method
- MOCK_CONST_METHOD( name, arity, signature[, identifier] )         // generates only the const version of the method, if 'identifier' is omitted it will default to 'name'
+ MOCK_NON_CONST_METHOD( name, arity[, signature[, identifier]] )     // generates only the non-const version of the method
- MOCK_NON_CONST_METHOD( name, arity, signature[, identifier] )     // generates only the non-const version of the method, if 'identifier' is omitted it will default to 'name'
  
- MOCK_METHOD_TPL( name, arity, signature[, identifier] )           // must be used if the signature uses a template parameter of the class, if 'identifier' is omitted it will default to 'name'
+ MOCK_METHOD_TPL( name, arity[, signature[, identifier]] )           // must be used if the signature uses a template parameter of the class, generates both const and non-const methods
- MOCK_CONST_METHOD_TPL( name, arity, signature[, identifier] )     // must be used if the signature uses a template parameter of the class, if 'identifier' is omitted it will default to 'name'
+ MOCK_CONST_METHOD_TPL( name, arity[, signature[, identifier]] )     // must be used if the signature uses a template parameter of the class, generates only the const version of the method
- MOCK_NON_CONST_METHOD_TPL( name, arity, signature[, identifier] ) // must be used if the signature uses a template parameter of the class, if 'identifier' is omitted it will default to 'name'
+ MOCK_NON_CONST_METHOD_TPL( name, arity[, signature[, identifier]] ) // must be used if the signature uses a template parameter of the class, generates only the non-const version of the method
 
-[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]
+[note If the identifier is omitted it will default to the method name.]
 
-[note The signature must be surrounded with round parenthesis if the return type contains a comma]
+[note If the method name is not ambiguous both the signature and the identifier can be ommitted in the context of a derived MOCK_BASE_CLASS or base_type typedef.]
+
+[note The signature must be surrounded with round parenthesis if the return type contains a comma.]
+
+[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.
+
+Synopsis :
+ 
+ MOCK_METHOD_EXT( name, arity, signature, identifier )               // generates both const and non-const methods
+ MOCK_CONST_METHOD_EXT( name, arity, signature, identifier )         // generates only the const version of the method
+ MOCK_NON_CONST_METHOD_EXT( name, arity, signature, identifier )     // generates only the non-const version of the method
+ 
+ MOCK_METHOD_EXT_TPL( name, arity, signature, identifier )           // must be used if the signature uses a template parameter of the class, generates both const and non-const methods
+ MOCK_CONST_METHOD_EXT_TPL( name, arity, signature, identifier )     // must be used if the signature uses a template parameter of the class, generates only the const version of the method
+ MOCK_NON_CONST_METHOD_EXT_TPL( name, arity, signature, identifier ) // must be used if the signature uses a template parameter of the class, generates only the non-const version of the method
+
+Of course those macros are also available for compilers which support variadic macros.
 
 Example :
 
@@ -101,8 +118,6 @@ Example :
 
 [member_function_example_2]
 
-[note For a compiler not supporting variadic macros MOCK_METHOD_EXT must be used instead]
-
 Example :
 
 [member_function_example_3]
@@ -135,6 +150,8 @@ 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.]
+
 Example :
 
 [static_member_function_example_1]
@@ -227,6 +244,8 @@ 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.]
+
 Example :
 
 [function_example_1]