Changed layout to match boost

doc/customization.qbk

@@ -0,0 +1,163 @@
+[/
+ / Copyright (c) 2014 Mathieu Champlon
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section Customization]
+[import example/customization.cpp]
+
+This section explains how to customize different aspects of the library.
+
+[section Logging]
+
+The library will perform logging lazily, e.g. only when actually needed, which is usually because an error happens but it depends on the [link turtle.customization.test_framework_integration test framework integration] used.
+Parameters and [link turtle.customization.constraints constraints] are serialized to report meaningful diagnostics of the failures.
+
+By default the library attempts to serialize to an std::ostream and if this is not possible will use a '?'.
+
+[note Any incomplete type is gracefully handled and yields a '?'.]
+
+[warning Serializing a type inconsistently (including across several translation units) violates the [@http://en.wikipedia.org/wiki/One_Definition_Rule One Definition Rule].]
+
+If for some reason the serialization to an std::ostream shouldn't be used, it can be overridden by a serialization operator to a mock::stream, for instance to log user_type declared in user_namespace :
+
+[mock_stream_user_type]
+
+The operator is found using [@http://en.wikipedia.org/wiki/Argument-dependent_name_lookup argument-dependent name lookup] which means it needs to be in the namespace of either one of its arguments.
+The easiest is to define it in the same namespace as the type being serialized. If this is not possible (for instance when serializing a type in namespace std because the C++ standard explicitly forbids adding definitions into the std namespace) a serialization operator to mock::stream can be in the mock namespace instead.
+
+The serialization operators detection doesn't attempt to do conversions when looking for a match (because this can sometimes yield an ambiguous resolution error).
+As conversions can prove convenient, for instance when dealing with a base class which is derived to a lot of sub-classes, they can be activated by defining MOCK_USE_CONVERSIONS prior to including the library :
+
+[mock_use_conversions]
+
+Be aware though that in this case the compiler can produce a compilation error when attempting to detect whether serialization operators exist or not.
+It is always possible however to define a serialization operator to a mock::stream in order to bypass the detection.
+
+In all custom operator implementations it is probably a good thing to rely on the same mechanism the library uses in order to log everything, for instance here is how std::pair is handled :
+
+ namespace mock
+ {
+     template< typename T1, typename T2 >
+     mock::stream& operator<<( mock::stream& s, const std::pair< T1, T2 >& p )
+     {
+         return s << '(' << mock::format( p.first ) << ',' << mock::format( p.second ) << ')';
+     }
+ }
+
+The interesting part is the call to mock::format which enables the whole can-be-serialized-or-? logics.
+
+[endsect]
+
+[section Constraints]
+
+Constraint provide a means to validate the parameters received in a call to a mock object.
+
+The library comes with a set of pre-defined [link turtle.reference.expectation.constraints constraints] matching the most widely used cases, however it is quite common to need to perform a custom validation.
+
+Creating a constraint can be as simple as writing a function, for instance :
+
+[custom_constraint_free_function]
+
+Any functor will actually do as long as its signature matches the requirement : take a type convertible from the actual type and return a boolean.
+
+Using the custom constraint is also pretty trivial, for instance :
+
+[custom_constraint_free_function_test]
+
+Simple enough, however this constraint isn't serializable and thus yields a rather uninformative '?' in the logs.
+
+Just like a parameter, a constraint can be displayed in a readable form using its serialization operator, see [link turtle.customization.logging logging].
+
+Thus a widely used constraint (for instance one shipped with the code of a library) is likely better defined like this :
+
+[custom_constraint_functor]
+
+And of course the constraint is to be used in a slightly different way :
+
+[custom_constraint_functor_test]
+
+Actually real world use cases sometimes need several other features as well :
+
+* a state
+* (template) parameters
+* an operator with one or several (template) signatures
+
+Therefore a more realistic and complete example would be :
+
+[near_constraint]
+
+And it would be used like this :
+
+[near_constraint_test]
+
+The purpose of the 'near' template function is to :
+
+* remove the burden of specifying the template parameter when instantiating near_constraint
+* wrap the constraint in a mock::constraint so that it plays nicely with !, && and ||.
+
+The use of boost::unwrap_ref provides support for passing arguments as references with boost::ref and boost::cref and delaying their initialization, for instance :
+
+[near_constraint_cref_test]
+
+See [link turtle.reference.expectation.constraints constraints] for an explanation of how the library detects whether an argument is a functor or a value.
+
+For more information about the serialization operator and the use of mock::format, refer to [link turtle.customization.logging logging].
+
+[note The [link turtle.reference.constraint constraint helper macro] takes care of everything for simple cases.]
+
+[endsect]
+
+[section Number of arguments]
+
+The maximum number of arguments a mocked method can have is defined by MOCK_MAX_ARGS.
+By default this value is set to 9, but if needed it can be changed before including the library :
+
+[max_args]
+
+This means methods with up to 20 arguments will then be accepted.
+
+The mock object library uses several boost libraries and will adjust some of their constants if they haven't already been defined :
+
+* Boost.Function with BOOST_FUNCTION_MAX_ARGS required at MOCK_MAX_ARGS or higher
+* Boost.FunctionTypes with BOOST_FT_MAX_ARITY required at MOCK_MAX_ARGS + 1 or higher
+
+A compilation error will happen if one of those constants is already defined too low.
+
+[endsect]
+
+[section Test framework integration]
+
+By default the library expects to be used in conjunction with Boost.Test e.g. :
+
+* logs using the logger from Boost.Test
+* throws mock::exception deriving from boost::execution_aborted via boost::enable_current_exception
+* adds Boost.Test checkpoints whenever possible
+* verifies and resets all remaining (static or leaked objects) with a global fixture
+
+However integrating with any given unit test framework can be done by defining a custom error policy implementing the following concept :
+
+[custom_policy]
+
+The context, which stands for "something serializable to an std::ostream", is actually built only if an attempt to serialize it is made, thus enabling lazy serialization of all elements (e.g. constraints and parameters).
+File and line show were the expectation has been configured.
+
+The policy can then be activated by defining MOCK_ERROR_POLICY prior to including the library :
+
+[define_custom_policy]
+
+[endsect]
+
+[section Thread safety]
+
+Thread safety is not activated by default however defining MOCK_THREAD_SAFE before including the library will make creations and calls to mock objects thread-safe :
+
+[thread_safe]
+
+If available the library will rely on the C++11 standard mutexes and locks, otherwise Boost.Thread will be used.
+
+[endsect]
+
+[endsect]