Changeset 7401 for code/trunk/src/libraries/core/CoreIncludes.h

Timestamp:

Sep 11, 2010, 12:34:00 AM (14 years ago)

Author:

landauf

Message:

merged doc branch back to trunk

Location:

code/trunk

Files:

• . (modified) (1 prop)
• src/libraries/core/CoreIncludes.h (modified) (8 diffs)

code/trunk/src/libraries/core/CoreIncludes.h

@@ -28 +28 @@
 
 /**
+    @defgroup Factory RegisterObject() and CreateFactory()
+    @ingroup Object
+*/
+
+/**
     @file
-    @brief Definition of macros for Identifiers
+    @ingroup Object Factory
+    @brief Defines several very important macros used to register objects, create factories, and to work with identifiers.
 
-    Every class needs the RegisterObject(class) macro in its constructor. If the class is an interface
-    or the BaseObject itself, it needs the macro RegisterRootObject(class) instead.
+    Every class needs the @c RegisterObject(class) macro in its constructor. If the class is an interface
+    or the @c BaseObject itself, it needs the macro @c RegisterRootObject(class) instead.
 
-    To allow the object being created through the factory, use the CreateFactory(class) macro outside
-    the of the class implementation, so it gets executed before main().
+    To allow the object being created through the factory, use the @c CreateFactory(class) macro outside
+    of the class implementation, so it gets executed statically before @c main(). This will at the same time
+    register @a class in the class-hierarchy. If you don't want @a class to be loadable, but still
+    register it, call @c CreateUnloadableFactory(class).
+
+    Example:
+    @code
+    // Create the factory for MyClass
+    CreateFactory(MyClass);
+
+    // Constructor:
+    MyClass::MyClass()
+    {
+        // Register the object in the Identifier of MyClass
+        RegisterObject(MyClass);
+    }
+    @endcode
+
+    This file also defines a number of other useful macros, like, for example, @c Class(class) which
+    returns the @ref orxonox::Identifier "Identifier" of @a class, or @c ClassByString("class") which
+    returns the Identifier of a class with name @a "class".
+
+    Example:
+    @code
+    // Assigns the Identifier of MyClass
+    Identifier* identifier = Class(MyClass);
+    @endcode
+    @code
+    // Assigns the Identifier of a class named "MyClass"
+    Identifier* identifier = ClassByString("MyClass");
+    @endcode
 */
 
@@ -51 +86 @@
 
 /**
-    @brief Intern macro, containing the common parts of RegisterObject and RegisterRootObject.
+    @brief Intern macro, containing the common parts of @c RegisterObject and @c RegisterRootObject.
     @param ClassName The name of the class
-    @param bRootClass True if the class is directly derived from OrxonoxClass
+    @param bRootClass True if the class is directly derived from orxonox::OrxonoxClass
 */
 #define InternRegisterObject(ClassName, bRootClass) \
@@ -62 +97 @@
 
 /**
-    @brief RegisterObject - with and without debug output.
+    @brief Registers a newly created object in the core. Has to be called at the beginning of the constructor of @a ClassName.
     @param ClassName The name of the class
 */
@@ -69 +104 @@
 
 /**
-    @brief RegisterRootObject - with and without debug output.
+    @brief Registers a newly created object in the core. Has to be called at the beginning of the constructor of @a ClassName.
     @param ClassName The name of the class
+
+    In contrast to RegisterObject, this is used for classes that inherit directly from
+    orxonox::OrxonoxClass, namely all interfaces and orxonox::BaseObject.
 */
 #define RegisterRootObject(ClassName) \
@@ -101 +139 @@
     /**
         @brief Returns the Identifier with a given name.
-        @param String The name of the class
+        @param name The name of the class
     */
     inline Identifier* ClassByString(const std::string& name)
@@ -110 +148 @@
     /**
         @brief Returns the Identifier with a given lowercase name.
-        @param String The lowercase name of the class
+        @param name The lowercase name of the class
     */
     inline Identifier* ClassByLowercaseString(const std::string& name)
@@ -119 +157 @@
     /**
         @brief Returns the Identifier with a given network ID.
-        @param networkID The network ID of the class
+        @param id The network ID of the class
     */
     inline Identifier* ClassByID(uint32_t id)
@@ -130 +168 @@
         @note This of course only works with OrxonoxClasses.
               The only use is in conjunction with macros that don't know the class type.
-        @param Pointer to an OrxonoxClass
+        @param object Pointer to an OrxonoxClass
     */
     template <class T>