Changeset 7352 for code/branches/doc/src/libraries/util

Timestamp:

Sep 4, 2010, 11:33:02 PM (14 years ago)

Author:

landauf

Message:

added documentation

also some small naming and readability changes in the code.

Location:

code/branches/doc/src/libraries/util

Files:

• Debug.h (modified) (1 diff)
• Math.h (modified) (1 diff)
• MultiType.h (modified) (1 diff)
• MultiTypeValue.h (modified) (1 diff)
• Scope.h (modified) (1 diff)
• ScopedSingletonManager.h (modified) (1 diff)
• SharedPtr.h (modified) (1 diff)
• Singleton.h (modified) (1 diff)
• SmallObjectAllocator.h (modified) (1 diff)
• StringUtils.h (modified) (1 diff)
• SubString.cc (modified) (1 diff)
• SubString.h (modified) (1 diff)
• VA_NARGS.h (modified) (1 diff)

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

@@ -35 +35 @@
 /**
 @file
-@ingroup Util COUT
+@ingroup COUT
 @brief
     Handles different output-levels of errors, warnings, infos, and debug information.

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

@@ -34 +34 @@
 /**
     @file
-    @ingroup Util Math
+    @ingroup Math
     @brief Declaration and implementation of several math-functions, typedefs of some Ogre::Math classes to the orxonox namespace.
 */

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

@@ -34 +34 @@
 /**
     @file
-    @ingroup Util MultiType
+    @ingroup MultiType
     @brief Declaration of the MultiType and some helper constructs.
 

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

@@ -29 +29 @@
 /**
     @file
-    @ingroup Util MultiType
+    @ingroup MultiType
     @brief Declaration and Implementation of the MT_Value<T> class.
 

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

@@ -29 +29 @@
 /**
 @file
-@ingroup Util SingletonScope
+@ingroup SingletonScope
 @brief Declaration of the classes that are needed to use Scopes:
 orxonox::Scope, orxonox::ScopeListener, and orxonox::ScopeManager.

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

@@ -29 +29 @@
 /**
     @file
-    @ingroup Util SingletonScope
+    @ingroup SingletonScope
     @brief Definition of orxonox::ScopedSingletonManager, orxonox::ClassScopedSingletonManager, and the ManageScopedSingleton macro.
 

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

@@ -29 +29 @@
 /**
     @defgroup SharedPtr SharedPtr<T>
-    @ingroup Util Object
+    @ingroup Util
 */
 
 /**
     @file
-    @ingroup Util SharedPtr
+    @ingroup SharedPtr
     @brief Definition of the SharedPtr template that is used to manage pointers.
 

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

@@ -34 +34 @@
 /**
     @file
-    @ingroup Util SingletonScope
+    @ingroup SingletonScope
     @brief Definition of the Singleton template that is used as base class for classes that allow only one instance.
 

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

@@ -29 +29 @@
 /**
     @defgroup SmallObjectAllocator SmallObjectAllocator
-    @ingroup Util Object
+    @ingroup Util
 */
 
 /**
     @file
-    @ingroup Util SmallObjectAllocator
+    @ingroup SmallObjectAllocator
     @brief Declaration of SmallObjectAllocator
 

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

@@ -34 +34 @@
 /**
     @file
-    @ingroup Util String
+    @ingroup String
     @brief Declaration of several string manipulation functions, used in many parts of the game.
 */

code/branches/doc/src/libraries/util/SubString.cc

@@ -37 +37 @@
  *   Extended by Fabian 'x3n' Landau by the SL_PARENTHESES mode.
  */
+
+/**
+    @file
+    @brief Implementation of the SubString class.
+*/
 
 #include "SubString.h"

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

@@ -39 +39 @@
  /**
     @file
-    @ingroup Util String
-    @brief a small class to get the parts of a string separated by commas
+    @ingroup String
+    @brief A helper class to split a string into several tokens.
 
     @anchor SubStringExample

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

@@ -31 +31 @@
     @ingroup Util
     @brief Declaration of the ORXONOX_VA_NARGS macro which returns the number of arguments passed to a variadic macro.
+
+    With this utility you can overload a macro for different numbers of arguments
+    (of course overloading is not possible for different types, as macros are not
+    type aware, but for different numbers of arguments is still very powerful).
+
+    Example: A macro to call functions
+    @code
+    myfunction();                                           // A static function
+    MyClass::myStaticFunction();                            // A static class function
+    MyClass::myFunction();                                  // A member function
+
+    #define CallFunction(...) \                             // Define a variadic macro that passes the arguments to the overloaded implementations
+        BOOST_PP_EXPAND(BOOST_PP_CAT(CallFunction, ORXONOX_VA_NARGS(__VA_ARGS__))(__VA_ARGS__))
+
+    #define CallFunction1(function) \                       // Overloaded macro for 1 argument
+        function()                                          // Calls the static function
+
+    #define CallFunction2(class, function) \                // Overloaded macro for 2 arguments
+        class::function()                                   // Calls the static class function
+
+    #define CallFunction3(class, function, object) \        // Overloaded macro for 3 arguments
+        object->class::function()                           // Calls the function on the object
+
+
+    CallFunction(myFunction);                               // Call the macro with 1 argument
+    CallFunction(MyClass, myStaticFunction);                // Call the macro with 2 arguments
+    CallFunction(MyClass, myFunction, new MyClass());       // Call the macro with 3 arguments
+    @endcode
+
+    Note that the first (variadic) macro concatenates the name "CallFunction" with
+    the number of arguments ("1" - "N"). Then all arguments are passed to the right macro.
 */