Changeset 10418

Timestamp:

May 3, 2015, 1:54:43 PM (9 years ago)

Author:

landauf

Message:

improved documentation

Location:

code/branches/core7/src/libraries

Files:

• core/UpdateListener.h (modified) (1 diff)
• core/singleton/ScopedSingletonManager.h (modified) (1 diff)
• util/Singleton.h (modified) (1 diff)

code/branches/core7/src/libraries/core/UpdateListener.h

@@ -36 +36 @@
 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
     {

code/branches/core7/src/libraries/core/singleton/ScopedSingletonManager.h

@@ -61 +61 @@
     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) \

code/branches/core7/src/libraries/util/Singleton.h

@@ -68 +68 @@
     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