Changeset 7323 for code/branches/doc/src/libraries/util/Scope.h

Timestamp:

Sep 2, 2010, 3:16:08 AM (14 years ago)

Author:

landauf

Message:

added documentation

File:

• code/branches/doc/src/libraries/util/Scope.h (modified) (5 diffs)

code/branches/doc/src/libraries/util/Scope.h

@@ -27 +27 @@
  */
 
+/**
+@file
+@ingroup Util SingletonScope
+@brief Declaration of the classes that are needed to use Scopes:
+orxonox::Scope, orxonox::ScopeListener, and orxonox::ScopeManager.
+
+@anchor Scope
+
+A virtual scope can be represented by an instance of class orxonox::Scope. orxonox::Scope<@a scope> is a template
+an its template argument defines the name of the virtual scope. See orxonox::ScopeID for an enumeration of the
+available values for @a scope. The orxonox::Scope object for a given @a scope can be activated or deactivated.
+Instances of orxonox::ScopeListener can register for a given @a scope and will get a notification if the
+corresponding orxonox::Scope object changes its state.
+
+To avoid multiple instances of orxonox::Scope<@a scope> in different libraries, each instance of orxonox::Scope
+registers in orxonox::ScopeManager, where they are linked statically in the util library.
+
+Scopes are usually used to control the creation and destruction of Singletons.
+
+@see orxonox::ScopedSingletonManager
+@see orxonox::Singleton
+*/
+
 #ifndef __Util_Scope_H__
 #define __Util_Scope_H__
@@ -42 +65 @@
 {
     /**
-        @brief The ScopeManager stores the variables of the scope templates in a statically linked context.
+        @brief The ScopeManager stores the variables of the Scope templates in a statically linked context.
+
+        If all Scope objects are managed by this class, they are statically linked in the util library.
+        Without this, a new instance of Scope<T> for each T would be created in every library of Orxonox,
+        which is of course not the desired behavior.
+
+        @see See @ref Scope "this description" for details about the interrelationship of Scope, ScopeListener, and ScopeManager.
     */
     class _UtilExport ScopeManager
@@ -56 +85 @@
 
     /**
-        @brief ScopeListeners register themselves in the corresponding scope and wait for notifications.
+        @brief ScopeListeners register themselves in the corresponding Scope and wait for notifications.
+        Notifications are sent if a Scope is activated or deactivated.
+
+        @see See @ref Scope "this description" for details about the interrelationship of Scope, ScopeListener, and ScopeManager.
     */
     class _UtilExport ScopeListener
@@ -86 +118 @@
         Objects inheriting from a ScopeListener are registered in a list (different for each scope).
         If the scope gets activated or deactivated, all objects in this list are notified.
+
+        @see See @ref Scope "this description" for details about the interrelationship of Scope, ScopeListener, and ScopeManager.
     */
     template <ScopeID::Value scope>
@@ -130 +164 @@
             }
 
+            //! Deactivates the listeners of this scope in case the scope is destroyed or the construction fails.
             void deactivateListeners()
             {