[Orxonox-commit 5758] r10418 - in code/branches/core7/src/libraries: core core/singleton util

[landauf at orxonox.net]

Author: landauf
Date: 2015-05-03 13:54:43 +0200 (Sun, 03 May 2015)
New Revision: 10418

Modified:
   code/branches/core7/src/libraries/core/UpdateListener.h
   code/branches/core7/src/libraries/core/singleton/ScopedSingletonManager.h
   code/branches/core7/src/libraries/util/Singleton.h
Log:
improved documentation

Modified: code/branches/core7/src/libraries/core/UpdateListener.h
===================================================================
--- code/branches/core7/src/libraries/core/UpdateListener.h	2015-05-03 11:31:18 UTC (rev 10417)
+++ code/branches/core7/src/libraries/core/UpdateListener.h	2015-05-03 11:54:43 UTC (rev 10418)
@@ -35,6 +35,20 @@
 
 namespace orxonox
 {
+    /**
+     * Inherit from UpdateListener if you need to receive calls before or after the game is ticked. All classes inheriting from UpdateListener
+     * need to be strictly independent of each other and may not rely on a specific order in which all UpdateListeners are called.
+     *
+     * If you do have such a dependency between two UpdateListeners, e.g. A::preUpdate() always needs to be called before B::preUpdate(), then
+     * you need to create a third class C (which inherits from UpdateListener) with the following implementation:
+     * void C::preUpdate()
+     * {
+     *     A::preUpdate();
+     *     B::preUpdate();
+     * }
+     * This is the only way to ensure that A gets called before B. In this example, only C inherits from UpdateListener, while A and B do not.
+     * Instead they receive the update from C.
+     */
     class _CoreExport UpdateListener : virtual public Listable
     {
         public:

Modified: code/branches/core7/src/libraries/core/singleton/ScopedSingletonManager.h
===================================================================
--- code/branches/core7/src/libraries/core/singleton/ScopedSingletonManager.h	2015-05-03 11:31:18 UTC (rev 10417)
+++ code/branches/core7/src/libraries/core/singleton/ScopedSingletonManager.h	2015-05-03 11:54:43 UTC (rev 10418)
@@ -60,6 +60,26 @@
 
     If this macro is called for a singleton, it is registered with ScopedSingletonManager
     and will thus be created if its scope becomes active and destroyed if is deactivated.
+
+
+    Usually a singleton gets created automatically when it is first used, but it will never
+    be destroyed (unless the singleton explicitly deletes itself). To allow controlled
+    construction and destruction, the singleton can be put within a virtual scope. This is
+    done by registering the singleton class with orxonox::ScopedSingletonManager. To
+    do so, the ManageScopedSingleton() macro has to be called:
+
+    @code
+    ManageScopedSingleton(TestSingleton, ScopeID::Graphics, false); // muste be called in a source (*.cc) file
+    @endcode
+
+    @b Important: If you call ManageScopedSingleton(), you don't have to initialize singletonPtr_s anymore,
+    because that's already done by the macro.
+
+    Now the singleton TestSingleton gets automatically created if the scope Graphics becomes
+    active and also gets destroyed if the scope is deactivated.
+
+    Note that not all singletons must register with a scope, but it's recommended.
+
 */
 #define ManageScopedSingleton(className, scope, allowedToFail) \
     className* className::singletonPtr_s = NULL; \

Modified: code/branches/core7/src/libraries/util/Singleton.h
===================================================================
--- code/branches/core7/src/libraries/util/Singleton.h	2015-05-03 11:31:18 UTC (rev 10417)
+++ code/branches/core7/src/libraries/util/Singleton.h	2015-05-03 11:54:43 UTC (rev 10418)
@@ -68,24 +68,6 @@
     TestSingleton* TestSingleton::singletonPtr_s = NULL;
     @endcode
 
-    Usually a singleton gets created automatically when it is first used, but it will never
-    be destroyed (unless the singleton explicitly deletes itself). To allow controlled
-    construction and destruction, the singleton can be put within a virtual scope. This is
-    done by registering the singleton class with orxonox::ScopedSingletonManager. To
-    do so, the ManageScopedSingleton() macro has to be called:
-
-    @code
-    ManageScopedSingleton(TestSingleton, ScopeID::Graphics, false); // muste be called in a source (*.cc) file
-    @endcode
-
-    @b Important: If you call ManageScopedSingleton(), you don't have to initialize singletonPtr_s anymore,
-    because that's already done by the macro.
-
-    Now the singleton TestSingleton gets automatically created if the scope Graphics becomes
-    active and also gets destroyed if the scope is deactivated.
-
-    Note that not all singletons must register with a scope, but it's recommended.
-
     If a class inherits from orxonox::Singleton, it also inherits its functions. The most important
     function is orxonox::Singleton::getInstance() which returns a reference to the only instance
     of the singleton.