add warnings in the documentation about the special lifetime when using SmallObjects

git-svn-id: svn://svn.code.sf.net/p/loki-lib/code/trunk@653 7ec92016-0320-0410-acc4-a06ded1c099a

include/loki/Factory.h

@@ -686,6 +686,13 @@ template <typename AP, typename Id, typename P1 >
 ///  
 ///  Create functions can have up to 15 parameters.
 ///    
+///  \par Singleton lifetime when used with Loki::SingletonHolder
+///  Because Factory uses internally Functors which inherits from 
+///  SmallObject you must use the singleton lifetime
+///  \code Loki::LongevityLifetime::DieAsSmallObjectChild \endcode
+///  Alternatively you could suppress for Functor the inheritance 
+///  from SmallObject by defining the macro:
+/// \code LOKI_FUNCTOR_IS_NOT_A_SMALLOBJECT \endcode
 ////////////////////////////////////////////////////////////////////////////////
     template
     <
@@ -1033,6 +1040,9 @@ template <typename AP, typename Id, typename P1 >
 #endif // FACTORY_INC_
 
 // $Log$
+// Revision 1.17  2006/05/20 10:23:07  syntheticpp
+// add warnings in the documentation about the special lifetime when using SmallObjects
+//
 // Revision 1.16  2006/03/08 16:41:38  syntheticpp
 // remove second $
 //

include/loki/Functor.h

@@ -30,14 +30,6 @@
 
 ///  \defgroup FunctorGroup Function objects
 
-/// \def LOKI_FUNCTOR_IS_NOT_A_SMALLOBJECT
-/// \ingroup FunctorGroup
-/// Define to avoid static instantiation/delete order problems.
-/// Removes crashes when using static Functors and multi threading.
-/// Defining also removes problems when unloading Dlls which defines
-/// static Functor objects.
-/// So being a Loki::SmallValueObj limits the value of Functor
-/// and Function and makes them more different to tr1::function.
 #ifndef LOKI_FUNCTOR_IS_NOT_A_SMALLOBJECT
 //#define LOKI_FUNCTOR_IS_NOT_A_SMALLOBJECT
 #endif
@@ -1161,6 +1153,15 @@ namespace Loki
 ///
 ///  \ingroup FunctorGroup
 ///  A generalized functor implementation with value semantics
+///
+/// \par Macro: LOKI_FUNCTOR_IS_NOT_A_SMALLOBJECT
+/// Define 
+/// \code LOKI_FUNCTOR_IS_NOT_A_SMALLOBJECT \endcode
+/// to avoid static instantiation/delete 
+/// order problems.
+/// It often helps against crashes when using static Functors and multi threading.
+/// Defining also removes problems when unloading Dlls which hosts
+/// static Functor objects.
 ////////////////////////////////////////////////////////////////////////////////
     template <typename R = void, class TList = NullType,
         template<class, class> class ThreadingModel = LOKI_DEFAULT_THREADING_NO_OBJ_LEVEL>
@@ -1688,6 +1689,9 @@ namespace Loki
 #endif  // FUNCTOR_INC_
 
 // $Log$
+// Revision 1.20  2006/05/20 10:23:07  syntheticpp
+// add warnings in the documentation about the special lifetime when using SmallObjects
+//
 // Revision 1.19  2006/03/08 18:22:42  syntheticpp
 // doxygen fixes
 //

include/loki/Singleton.h

@@ -40,6 +40,14 @@
 ///  \ingroup   SingletonGroup
 ///  \defgroup  LifetimeGroup Lifetime policies
 ///  \ingroup   SingletonGroup
+///  The lifetimes of the singleton.
+///  \par Special lifetime for SmallObjects
+///  When the holded object is a Small(Value)Object or the holded object 
+///  uses objects which are or inherit from Small(Value)Object
+///  then you can't use the default lifetime: you must use the lifetime
+///  \code Loki::LongevityLifetime::DieAsSmallObjectChild \endcode
+///  Be aware of this when you use Loki::Factory, Loki::Functor, or Loki::Function.
+
 
 
 namespace Loki
@@ -889,6 +897,9 @@ namespace Loki                                                          \
 #endif // SINGLETON_INC_
 
 // $Log$
+// Revision 1.30  2006/05/20 10:23:07  syntheticpp
+// add warnings in the documentation about the special lifetime when using SmallObjects
+//
 // Revision 1.29  2006/03/15 08:47:18  syntheticpp
 // gcc: specialization only in the correct namespace, thx to Sam Miller
 //