Changeset 447 for code/branches/objecthierarchy/src

Timestamp:

Dec 9, 2007, 11:21:14 PM (17 years ago)

Author:

landauf

Message:

• added comments and doxygen-tags to the ConfigValueContainer
• changed some comments in the other files

Location:

code/branches/objecthierarchy/src/orxonox/core

Files:

• ClassFactory.h (modified) (1 diff)
• ConfigValueContainer.cc (modified) (34 diffs)
• ConfigValueContainer.h (modified) (3 diffs)
• CoreIncludes.h (modified) (7 diffs)
• Factory.cc (modified) (2 diffs)
• Factory.h (modified) (3 diffs)
• Identifier.cc (modified) (2 diffs)
• Identifier.h (modified) (12 diffs)
• IdentifierList.cc (modified) (1 diff)
• Iterator.h (modified) (8 diffs)
• MetaObjectList.h (modified) (3 diffs)
• ObjectList.h (modified) (4 diffs)
• OrxonoxClass.h (modified) (4 diffs)

code/branches/objecthierarchy/src/orxonox/core/ClassFactory.h

@@ -34 +34 @@
     /**
         @brief Adds the ClassFactory to the Identifier of the same type and creates a new object to retrieve the parents.
-        @return True, because the compiler only allows assignments before main()
+        @return Always true (this is needed because the compiler only allows assignments before main())
     */
     template <class T>

code/branches/objecthierarchy/src/orxonox/core/ConfigValueContainer.cc

@@ -8 +8 @@
 namespace orxonox
 {
-    std::list<std::string>* ConfigValueContainer::configFileLines_s = 0;
-    bool ConfigValueContainer::readConfigFile_s = false;
-
+    std::list<std::string>* ConfigValueContainer::configFileLines_s = 0; // Set the static member variable configFileLines_s to zero
+    bool ConfigValueContainer::readConfigFile_s = false;                 // Set the static member variable readConfigFile_s to false
+
+    /**
+        @brief Constructor: Converts the default-value to a string, checks the config-file for a changed value, sets this->value_int_.
+        @param classname The name of the class the variable belongs to
+        @param varname The name of the variable
+        @param defvalue The default-value
+    */
     ConfigValueContainer::ConfigValueContainer(const std::string& classname, const std::string& varname, int defvalue)
     {
+        // Try to convert the default-value from int to string
         std::ostringstream ostream;
-
         if (ostream << defvalue)
             this->defvalue_ = ostream.str();
@@ -20 +26 @@
             this->defvalue_ = "0";
 
+        // Set the default values, then get the value-string
         this->setDefaultValues(classname, varname);
         std::string valueString = this->getValueString();
 
+        // Try to convert the value-string to int
         std::istringstream istream(valueString);
         if (!(istream >> this->value_int_))
         {
+            // The conversion failed - use the default value and restore the entry in the config-file
             this->value_int_ = defvalue;
             (*this->configFileLine_) = this->varname_ + "=" + this->defvalue_;
@@ -32 +41 @@
     }
 
+    /**
+        @brief Constructor: Converts the default-value to a string, checks the config-file for a changed value, sets this->value_double_.
+        @param classname The name of the class the variable belongs to
+        @param varname The name of the variable
+        @param defvalue The default-value
+    */
     ConfigValueContainer::ConfigValueContainer(const std::string& classname, const std::string& varname, double defvalue)
     {
+        // Try to convert the default-value from double to string
         std::ostringstream ostream;
-
         if (ostream << defvalue)
             this->defvalue_ = ostream.str();
@@ -41 +56 @@
             this->defvalue_ = "0.000000";
 
+        // Set the default values, then get the value-string
         this->setDefaultValues(classname, varname);
         std::string valueString = this->getValueString();
 
+        // Try to convert the value-string to double
         std::istringstream istream(valueString);
         if (!(istream >> this->value_double_))
         {
+            // The conversion failed - use the default value and restore the entry in the config-file
             this->value_double_ = defvalue;
             (*this->configFileLine_) = this->varname_ + "=" + this->defvalue_;
@@ -53 +71 @@
     }
 
+    /**
+        @brief Constructor: Converts the default-value to a string, checks the config-file for a changed value, sets this->value_bool_.
+        @param classname The name of the class the variable belongs to
+        @param varname The name of the variable
+        @param defvalue The default-value
+    */
     ConfigValueContainer::ConfigValueContainer(const std::string& classname, const std::string& varname, bool defvalue)
     {
+        // Convert the default-value from bool to string
         if (defvalue)
             this->defvalue_ = "true";
@@ -60 +85 @@
             this->defvalue_ = "false";
 
+        // Set the default values, then get the value-string
         this->setDefaultValues(classname, varname);
         std::string valueString = this->getValueString();
 
+        // Try to parse the value-string - is it a word?
         if (valueString.find("true") < valueString.size() || valueString.find("yes") < valueString.size())
             this->value_bool_ = true;
@@ -69 +96 @@
         else
         {
+            // Its not a known word - is it a number?
             std::istringstream istream(valueString);
             if (!(istream >> this->value_bool_))
             {
+                // The conversion failed - use the default value and restore the entry in the config-file
                 this->value_bool_ = defvalue;
                 (*this->configFileLine_) = this->varname_ + "=" + this->defvalue_;
@@ -79 +108 @@
     }
 
+    /**
+        @brief Constructor: Converts the default-value to a string, checks the config-file for a changed value, sets this->value_string_.
+        @param classname The name of the class the variable belongs to
+        @param varname The name of the variable
+        @param defvalue The default-value
+    */
     ConfigValueContainer::ConfigValueContainer(const std::string& classname, const std::string& varname, const char* defvalue)
     {
+        // Not much to do here - just set all member-variables and check the config-file
         this->defvalue_ = defvalue;
         this->setDefaultValues(classname, varname);
@@ -86 +122 @@
     }
 
+    /**
+        @brief Constructor: Converts the default-value to a string, checks the config-file for a changed value, sets this->value_vector3_.
+        @param classname The name of the class the variable belongs to
+        @param varname The name of the variable
+        @param defvalue The default-value
+    */
     ConfigValueContainer::ConfigValueContainer(const std::string& classname, const std::string& varname, Ogre::Vector3 defvalue)
     {
+        // Try to convert the default-value from Vector3 to string
         std::ostringstream ostream;
         if (ostream << "(" << defvalue.x << "," << defvalue.y << "," << defvalue.z << ")")
@@ -94 +137 @@
             this->defvalue_ = "(0,0,0)";
 
+        // Set the default values, then get the value-string
         this->setDefaultValues(classname, varname);
         std::string valueString = this->getValueString();
 
+        // Strip the value-string
+        valueString = this->getStrippedLine(valueString);
         unsigned int pos;
-        while ((pos = valueString.find(" ")) < valueString.length())
-            valueString.erase(pos, 1);
         while ((pos = valueString.find("(")) < valueString.length())
             valueString.erase(pos, 1);
@@ -107 +151 @@
             valueString.replace(pos, 1, " ");
 
+        // Try to convert the stripped value-string to Vector3
         std::istringstream istream(valueString);
-
         if (!(istream >> this->value_vector3_.x))
         {
+            // The conversion failed - use the default value and restore the entry in the config-file
             this->value_vector3_.x = defvalue.x;
             (*this->configFileLine_) = this->varname_ + "=" + this->defvalue_;
@@ -117 +162 @@
         if (!(istream >> this->value_vector3_.y))
         {
+            // The conversion failed - use the default value and restore the entry in the config-file
             this->value_vector3_.y = defvalue.y;
             (*this->configFileLine_) = this->varname_ + "=" + this->defvalue_;
@@ -123 +169 @@
         if (!(istream >> this->value_vector3_.z))
         {
+            // The conversion failed - use the default value and restore the entry in the config-file
             this->value_vector3_.z = defvalue.z;
             (*this->configFileLine_) = this->varname_ + "=" + this->defvalue_;
@@ -129 +176 @@
     }
 
+    /**
+        @brief Constructor: Converts the default-value to a string, checks the config-file for a changed value, sets this->value_colourvalue_.
+        @param classname The name of the class the variable belongs to
+        @param varname The name of the variable
+        @param defvalue The default-value
+    */
     ConfigValueContainer::ConfigValueContainer(const std::string& classname, const std::string& varname, Ogre::ColourValue defvalue)
     {
+        // Try to convert the default-value from ColourValue to string
         std::ostringstream ostream;
         if (ostream << "(" << defvalue.r << "," << defvalue.g << "," << defvalue.b << "," << defvalue.a << ")")
@@ -137 +191 @@
             this->defvalue_ = "(0,0,0,0)";
 
+        // Set the default values, then get the value-string
         this->setDefaultValues(classname, varname);
         std::string valueString = this->getValueString();
 
+        // Strip the value-string
+        valueString = this->getStrippedLine(valueString);
         unsigned int pos;
-        while ((pos = valueString.find(" ")) < valueString.length())
-            valueString.erase(pos, 1);
         while ((pos = valueString.find("(")) < valueString.length())
             valueString.erase(pos, 1);
@@ -150 +205 @@
             valueString.replace(pos, 1, " ");
 
+        // Try to convert the stripped value-string to Vector3
         std::istringstream istream(valueString);
-
         if (!(istream >> this->value_colourvalue_.r))
         {
+            // The conversion failed - use the default value and restore the entry in the config-file
             this->value_colourvalue_.r = defvalue.r;
             (*this->configFileLine_) = this->varname_ + "=" + this->defvalue_;
@@ -160 +216 @@
         if (!(istream >> this->value_colourvalue_.g))
         {
+            // The conversion failed - use the default value and restore the entry in the config-file
             this->value_colourvalue_.g = defvalue.g;
             (*this->configFileLine_) = this->varname_ + "=" + this->defvalue_;
@@ -166 +223 @@
         if (!(istream >> this->value_colourvalue_.b))
         {
+            // The conversion failed - use the default value and restore the entry in the config-file
             this->value_colourvalue_.b = defvalue.b;
             (*this->configFileLine_) = this->varname_ + "=" + this->defvalue_;
@@ -172 +230 @@
         if (!(istream >> this->value_colourvalue_.a))
         {
+            // The conversion failed - use the default value and restore the entry in the config-file
             this->value_colourvalue_.a = defvalue.a;
             (*this->configFileLine_) = this->varname_ + "=" + this->defvalue_;
@@ -178 +237 @@
     }
 
+    /**
+        @brief Sets the default values of the container and searches the coresponding entry in the config-file.
+        @param classname The name of the class the variable belongs to
+        @param varname The name of the variable
+    */
     void ConfigValueContainer::setDefaultValues(const std::string& classname, const std::string& varname)
     {
+        // Set the class and variable names
         this->classname_ = classname;
         this->varname_ = varname;
 
+        // Search the entry in the config-file
         this->searchConfigFileLine();
 
+        // Set the values of all types to zero
         this->value_int_ = 0;
         this->value_double_ = 0.000000;
@@ -193 +260 @@
     }
 
+    /**
+        @brief Searches the corresponding entry in the config-file and creates it, if there is no entry.
+    */
     void ConfigValueContainer::searchConfigFileLine()
     {
+        // Read the file if needed
         if (!ConfigValueContainer::readConfigFile_s)
             ConfigValueContainer::readConfigFile(CONFIGFILEPATH);
 
+        // Just in case something goes wrong
         this->configFileLine_ = 0;
 
+        // The string of the section we're searching
         std::string section = "";
         section.append("[");
@@ -205 +278 @@
         section.append("]");
 
+        // Iterate through all config-file-lines
         bool success = false;
         std::list<std::string>::iterator it1;
         for(it1 = ConfigValueContainer::configFileLines_s->begin(); it1 != ConfigValueContainer::configFileLines_s->end(); ++it1)
         {
+            // Don't try to parse comments
             if (this->isComment(*it1))
                 continue;
@@ -214 +289 @@
             if ((*it1).find(section) < (*it1).length())
             {
+                // We found the right section
                 bool bLineIsEmpty = false;
                 std::list<std::string>::iterator positionToPutNewLineAt;
 
+                // Iterate through all lines in the section
                 std::list<std::string>::iterator it2;
                 for(it2 = ++it1; it2 != ConfigValueContainer::configFileLines_s->end(); ++it2)
                 {
+                    // Don't try to parse comments
                     if (this->isComment(*it2))
                         continue;
 
+                    // This if-else block is used to write a new line right after the last line of the
+                    // section but in front of the following empty lines before the next section.
+                    // (So this helps to keep a nice formatting with empty-lines between sections in the config-file)
                     if (this->isEmpty(*it2))
                     {
@@ -239 +320 @@
                     }
 
+                    // Look out for the beginning of the next section
                     unsigned int open = (*it2).find("[");
                     unsigned int close = (*it2).find("]");
                     if ((open < (*it2).length()) && (close < (*it2).length()) && (open < close))
                     {
+                        // The next section startet, so our line isn't yet in the file - now we add it and safe the file
                         this->configFileLine_ = this->configFileLines_s->insert(positionToPutNewLineAt, this->varname_ + "=" + this->defvalue_);
                         ConfigValueContainer::writeConfigFile(CONFIGFILEPATH);
@@ -249 +332 @@
                     }
 
+                    // Look out for the variable-name
                     if ((*it2).find(this->varname_) < (*it2).length())
                     {
+                        // We found the right line - safe it and return
                         this->configFileLine_ = it2;
                         success = true;
@@ -256 +341 @@
                     }
                 }
+
+                // Check if we succeeded
                 if (!success)
                 {
+                    // Looks like we found the right section, but the file ended without containing our variable - so we add it and safe the file
                     this->configFileLine_ = this->configFileLines_s->insert(positionToPutNewLineAt, this->varname_ + "=" + this->defvalue_);
                     ConfigValueContainer::writeConfigFile(CONFIGFILEPATH);
@@ -265 +353 @@
             }
         }
+
+        // Check if we succeeded
         if (!success)
         {
-            this->configFileLines_s->push_back("[" + this->classname_ + "]");
-            this->configFileLines_s->push_back(this->varname_ + "=" + this->defvalue_);
-            this->configFileLine_ = --this->configFileLines_s->end();
+            // We obviously didn't found the right section, so we'll create it
+            this->configFileLines_s->push_back("[" + this->classname_ + "]");           // Create the section
+            this->configFileLines_s->push_back(this->varname_ + "=" + this->defvalue_); // Create the line
+            this->configFileLine_ = --this->configFileLines_s->end();                   // Set the pointer to the last element
             success = true;
-            this->configFileLines_s->push_back("");
-            ConfigValueContainer::writeConfigFile(CONFIGFILEPATH);
-        }
-    }
-
+            this->configFileLines_s->push_back("");                                     // Add an empty line - this is needed for the algorithm in the searchConfigFileLine-function
+            ConfigValueContainer::writeConfigFile(CONFIGFILEPATH);                      // Save the changed config-file
+        }
+    }
+
+    /**
+        @brief Determines if a line in the config-file is a comment.
+        @param line The line to check
+        @return True = it's a comment
+    */
     bool ConfigValueContainer::isComment(const std::string& line)
     {
+        // Strip the line, whitespaces are disturbing
         std::string teststring = getStrippedLine(line);
 
+        // There are four possible comment-symbols:
+        //  1) #comment in script-language style
+        //  2) %comment in matlab style
+        //  3) ;comment in unreal tournament config-file style
+        //  4) //comment in code style
         if (teststring[0] == '#' || teststring[0] == '%' || teststring[0] == ';' || (teststring[0] == '/' && teststring[0] == '/'))
             return true;
@@ -286 +388 @@
     }
 
+    /**
+        @brief Determines if a line in the config-file is empty (contains only whitespaces).
+        @param line The line to check
+        @return True = it's empty
+    */
     bool ConfigValueContainer::isEmpty(const std::string& line)
     {
@@ -291 +398 @@
     }
 
+    /**
+        @brief Removes all whitespaces from a line.
+        @param line The line to strip
+        @return The stripped line
+    */
     std::string ConfigValueContainer::getStrippedLine(const std::string& line)
     {
@@ -301 +413 @@
     }
 
+    /**
+        @brief Returns the part in the corresponding config-file-entry of the container that defines the value.
+        @param bStripped True = strip the value-string
+        @return The value-string
+    */
     std::string ConfigValueContainer::getValueString(bool bStripped)
     {
@@ -312 +429 @@
     }
 
+    /**
+        @brief Reads the config-file and stores the lines in a list.
+        @param filename The name of the config-file
+    */
     void ConfigValueContainer::readConfigFile(const std::string& filename)
     {
         ConfigValueContainer::readConfigFile_s = true;
 
+        // Create the list if needed
         if (!ConfigValueContainer::configFileLines_s)
             ConfigValueContainer::configFileLines_s = new std::list<std::string>;
 
+        // This creates the file if it's not existing
         std::ofstream createFile;
         createFile.open(filename.c_str(), std::fstream::app);
         createFile.close();
 
+        // Open the file
         std::ifstream file;
         file.open(filename.c_str(), std::fstream::in);
@@ -328 +452 @@
         char line[1024];
 
+        // Iterate through the file and add the lines into the list
         while (file.good() && !file.eof())
         {
@@ -335 +460 @@
         }
 
+        // The last line is useless
         ConfigValueContainer::configFileLines_s->pop_back();
 
+        // Add an empty line to the end of the file if needed
+        // this is needed for the algorithm in the searchConfigFileLine-function
         if ((ConfigValueContainer::configFileLines_s->size() > 0) && !isEmpty(*ConfigValueContainer::configFileLines_s->rbegin()))
         {
@@ -346 +474 @@
     }
 
+    /**
+        @param Writes the content of the list, containing all lines of the config-file, into the config-file.
+        @param filename The name of the config-file
+    */
     void ConfigValueContainer::writeConfigFile(const std::string& filename)
     {
-        ConfigValueContainer::readConfigFile_s = true;
-
-        if (!ConfigValueContainer::configFileLines_s)
-            ConfigValueContainer::configFileLines_s = new std::list<std::string>;
-
-        std::ofstream createFile;
-        createFile.open(filename.c_str(), std::fstream::app);
-        createFile.close();
-
+        // Make sure we stored the config-file in the list
+        if (!ConfigValueContainer::readConfigFile_s)
+            ConfigValueContainer::readConfigFile(filename);
+
+        // Open the file
         std::ofstream file;
         file.open(filename.c_str(), std::fstream::out);
 
+        // Iterate through the list an write the lines into the file
         std::list<std::string>::iterator it;
         for(it = ConfigValueContainer::configFileLines_s->begin(); it != ConfigValueContainer::configFileLines_s->end(); ++it)

code/branches/objecthierarchy/src/orxonox/core/ConfigValueContainer.h

@@ +1 @@
+/*!
+    @file ConfigValueContainer.h
+    @brief Definition of the ConfigValueContainer class.
+
+    The ConfigValueContainer class contains all needed informations about a configurable variable:
+     - the name of the variable
+     - the name of the class the variable belongs to
+     - the default value
+     - the user-specified value
+     - a pointer to the entry in the config-file
+
+    This is needed to assign the configured values to all newly created objects.
+*/
+
 #ifndef _ConfigValueContainer_H__
 #define _ConfigValueContainer_H__
@@ -9 +23 @@
 namespace orxonox
 {
+    //! The ConfigValuecontainer contains all needed informations about a configurable variable.
+    /**
+        The ConfigValueContainer class contains all needed informations about a configurable variable:
+         - the name of the variable
+         - the name of the class the variable belongs to
+         - the default value
+         - the user-specified value
+         - a pointer to the entry in the config-file
+
+        This is needed to assign the configured values to all newly created objects.
+
+        The container searches for the entry in the config file.
+        If there is an entry, it parses the specified value and assigns it to the variable of the right type.
+        If there is no entry, it adds the entry with the default-value to the section of the variables class.
+        If there is no section, the section and the entry are added to the end of the config-file.
+    */
     class ConfigValueContainer
     {
@@ -29 +59 @@
             static void writeConfigFile(const std::string& filename);
 
+            /** @returns the value of the type int. @param value This is only needed to determine the right type. */
             inline int getValue(int value)                                      { return this->value_int_; }
+            /** @returns the value of the type double. @param value This is only needed to determine the right type. */
             inline double getValue(double value)                                { return this->value_double_; }
+            /** @returns the value of the type bool. @param value This is only needed to determine the right type. */
             inline bool getValue(bool value)                                    { return this->value_bool_; }
+            /** @returns the value of the type std::string. @param value This is only needed to determine the right type. */
             inline std::string getValue(const std::string& value)               { return this->value_string_; }
+            /** @returns the value of the type Vector3. @param value This is only needed to determine the right type. */
             inline Ogre::Vector3 getValue(const Ogre::Vector3& value)           { return this->value_vector3_; }
+            /** @returns the value of the type Colour£Value. @param value This is only needed to determine the right type. */
             inline Ogre::ColourValue getValue(const Ogre::ColourValue& value)   { return this->value_colourvalue_; }
 
         private:
-            std::string         classname_;
-            std::string         varname_;
-            std::string         defvalue_;
+            std::string         classname_;                     //!< The name of the class the variable belongs to
+            std::string         varname_;                       //!< The name of the variable
+            std::string         defvalue_;                      //!< The string of the default-variable
 
-            int                 value_int_;
-            double              value_double_;
-            bool                value_bool_;
-            std::string         value_string_;
-            Ogre::Vector3       value_vector3_;
-            Ogre::ColourValue   value_colourvalue_;
+            int                 value_int_;                     //!< The value, if the variable is of the type int
+            double              value_double_;                  //!< The value, if the variable is of the type double
+            bool                value_bool_;                    //!< The value, if the variable is of the type bool
+            std::string         value_string_;                  //!< The value, if the variable is of the type string
+            Ogre::Vector3       value_vector3_;                 //!< The value, if the variable is of the type Vector3
+            Ogre::ColourValue   value_colourvalue_;             //!< The value, if the variable is of the type ColourValue
 
-            std::list<std::string>::iterator configFileLine_;
-            static std::list<std::string>* configFileLines_s;
-            static bool readConfigFile_s;
+            std::list<std::string>::iterator configFileLine_;   //!< An iterator, pointing to the entry of the variable in the config-file
+            static std::list<std::string>* configFileLines_s;   //!< A list, containing all entrys in the config-file
+            static bool readConfigFile_s;                       //!< True if the config-file is read and stored in the list
     };
 }

code/branches/objecthierarchy/src/orxonox/core/CoreIncludes.h

@@ -1 +1 @@
 /**
     @file CoreIncludes.h
-    @brief Definition of macros for the class-hierarchy and the factory.
+    @brief Definition of macros and typedefs.
 
     Every class needs the RegisterObject(class) macro in its constructor. If the class is an interface
@@ -21 +21 @@
 #include "OgreColourValue.h"
 
+
+// Some typedefs
 namespace orxonox
 {
@@ -27 +29 @@
 }
 
-// Intern macro, containing the common parts of RegisterObject and RegisterRootObject
+
+/**
+    @brief Intern macro, containing the common parts of RegisterObject and RegisterRootObject.
+    @param ClassName The name of the class
+    @param bRootClass True if the class is directly derived from OrxonoxClass
+*/
 #define InternRegisterObject(ClassName, bRootClass) \
     this->setIdentifier(ClassIdentifier<ClassName>::registerClass(this->getParents(), #ClassName, bRootClass)); \
@@ -34 +41 @@
     ClassIdentifier<ClassName>::addObject(this)
 
-// Intern macro, containing the specific part of RegisterRootObject
+/**
+    @brief Intern macro, containing the specific part of RegisterRootObject.
+    @param ClassName The name of the class
+*/
 #define InternRegisterRootObject(ClassName) \
     if (Identifier::isCreatingHierarchy() && !this->getParents()) \
@@ -40 +50 @@
     InternRegisterObject(ClassName, true)
 
-// RegisterObject - with and without debug output
+/**
+    @brief RegisterObject - with and without debug output.
+    @param ClassName The name of the class
+*/
 #if HIERARCHY_VERBOSE
 #define RegisterObject(ClassName) \
@@ -50 +63 @@
 #endif
 
-// RegisterRootObject - with and without debug output
+/**
+    @brief RegisterRootObject - with and without debug output.
+    @param ClassName The name of the class
+*/
 #if HIERARCHY_VERBOSE
 #define RegisterRootObject(ClassName) \
@@ -60 +76 @@
 #endif
 
-// Class(ClassName) returns the Identifier of the given class
+/**
+    @brief Returns the Identifier of the given class.
+    @param ClassName The name of the class
+*/
 #define Class(ClassName) \
     ClassIdentifier<ClassName>::getIdentifier()
 
-// Creates the entry in the Factory
+/**
+    @brief Creates the entry in the Factory.
+    @param ClassName The name of the class
+*/
 #define CreateFactory(ClassName) \
     bool bCreated##ClassName##Factory = ClassFactory<ClassName>::create()
 
-// ID(StringOrInt) returns the Identifier with either a given name or a given NetworkID through the factory
+/**
+    @brief Returns the Identifier with either a given name or a given network ID through the factory.
+    @param StringOrInt The name or the network ID of the class
+*/
 #define ID(StringOrInt) \
     Factory::getIdentifier(StringOrInt)
 
-// bla
+/**
+    @brief Assigns the value, defined in the config-file, to the variable (or the default-value, if there is no entry in the file).
+    @param varname The name of the variable
+    @param defvalue The default-value of the variable
+*/
 #define SetConfigValue(varname, defvalue) \
     ConfigValueContainer* container##varname = this->getIdentifier()->getConfigValueContainer(#varname); \

code/branches/objecthierarchy/src/orxonox/core/Factory.cc

@@ -24 +24 @@
 
     /**
-        @returns the Identifier with a given networkID.
-        @param id The networkID of the wanted Identifier
+        @returns the Identifier with a given network ID.
+        @param id The network ID of the wanted Identifier
     */
     Identifier* Factory::getIdentifier(const unsigned int id)
@@ -50 +50 @@
 
     /**
-        @brief Removes the entry with the old networkID and adds a new one.
+        @brief Removes the entry with the old network ID and adds a new one.
         @param identifier The identifier to change
         @param oldID The old networkID

code/branches/objecthierarchy/src/orxonox/core/Factory.h

@@ -3 +3 @@
     @brief Definition of the Factory and the BaseFactory class.
 
-    The Factory is a singleton, containing two maps to map either the name or the networkID
+    The Factory is a singleton, containing two maps to map either the name or the network ID
     of a class with the corresponding Identifier.
 
@@ -28 +28 @@
     // ###         Factory         ###
     // ###############################
-    //! The Factory is used to map name or networkID of a class with its Identifier.
+    //! The Factory is used to map the name or the network ID of a class with its Identifier.
     class Factory
     {
@@ -43 +43 @@
 
             static Factory* pointer_s;                                          //!< The pointer to the singleton
-            std::map<std::string, Identifier*> identifierStringMap_;            //!< The map mapping string with Identifier
-            std::map<unsigned int, Identifier*> identifierNetworkIDMap_;        //!< The map mapping networkID with Identifier
+            std::map<std::string, Identifier*> identifierStringMap_;            //!< The map, mapping the name with the Identifier
+            std::map<unsigned int, Identifier*> identifierNetworkIDMap_;        //!< The map, mapping the network ID with the Identifier
     };
 

code/branches/objecthierarchy/src/orxonox/core/Identifier.cc

@@ -12 +12 @@
     // ###############################
     int Identifier::hierarchyCreatingCounter_s = 0; // Set the static member variable hierarchyCreatingCounter_s to zero
-    unsigned int Identifier::classIDcounter_s = 0; // Set the static member variable classIDcounter_s to zero
+    unsigned int Identifier::classIDcounter_s = 0;  // Set the static member variable classIDcounter_s to zero
 
     /**
@@ -79 +79 @@
 
     /**
-        @brief Sets the networkID to a new value and changes the entry in the Factory.
-        @param id The new networkID
+        @brief Sets the network ID to a new value and changes the entry in the Factory.
+        @param id The new network ID
     */
     void Identifier::setNetworkID(unsigned int id)

code/branches/objecthierarchy/src/orxonox/core/Identifier.h

@@ -7 +7 @@
      - a list with all objects
      - parents and childs
-     - the factory, if available
+     - the factory (if available)
      - the networkID that can be synchronised with the server
+     - all configurable variables (if available)
 
     Every object has a pointer to the Identifier of its class. This allows the use isA(...),
@@ -18 +19 @@
 
     SubclassIdentifier is a separated class, acting like an Identifier, but has a given class.
-    You can only assign Identifiers of the given class or a derivative to a SubclassIdentifier.
+    You can only assign Identifiers of exactly the given class or of a derivative to a SubclassIdentifier.
 */
 
@@ -48 +49 @@
          - a list with all objects
          - parents and childs
-         - the factory, if available
+         - the factory (if available)
          - the networkID that can be synchronised with the server
+         - all configurable variables (if available)
 
         Every object has a pointer to the Identifier of its class. This allows the use isA(...),
@@ -87 +89 @@
             inline IdentifierList& getChildren() const { return *this->children_; }
 
-            /** @returns true, if a branch of the class-hierarchy is getting created, causing all new objects to store their parents. */
+            /** @returns true, if a branch of the class-hierarchy is being created, causing all new objects to store their parents. */
             inline static bool isCreatingHierarchy() { return (hierarchyCreatingCounter_s > 0); }
 
-            /** @returns the NetworkID to identify a class through the network. */
+            /** @returns the network ID to identify a class through the network. */
             inline const unsigned int getNetworkID() const { return this->classID_; }
 
+            /** @brief Sets the network ID to a new value. @param id The new value */
             void setNetworkID(unsigned int id);
 
+            /** @returns the ConfigValueContainer of a variable, given by the string of its name. @param varname The name of the variable */
             inline ConfigValueContainer* getConfigValueContainer(const std::string& varname)
                 { return this->configValues_[varname]; }
 
+            /** @brief Sets the ConfigValueContainer of a variable, given by the string of its name. @param varname The name of the variablee @param container The container */
             inline void setConfigValueContainer(const std::string& varname, ConfigValueContainer* container)
                 { this->configValues_[varname] = container; }
@@ -134 +139 @@
             std::string name_;                                          //!< The name of the class the Identifier belongs to
 
-            BaseFactory* factory_;                                      //!< The Factory, able to create new objects of the given class
+            BaseFactory* factory_;                                      //!< The Factory, able to create new objects of the given class (if available)
             bool bCreatedOneObject_;                                    //!< True if at least one object of the given type was created (used to determine the need of storing the parents)
             static int hierarchyCreatingCounter_s;                      //!< Bigger than zero if at least one Identifier stores its parents (its an int instead of a bool to avoid conflicts with multithreading)
-            static unsigned int classIDcounter_s;                       //!< The number of unique Identifiers
-            unsigned int classID_;                                      //!< The networkID to identify a class through the network
-            std::map<std::string, ConfigValueContainer*> configValues_;
+            static unsigned int classIDcounter_s;                       //!< The number of existing Identifiers
+            unsigned int classID_;                                      //!< The network ID to identify a class through the network
+            std::map<std::string, ConfigValueContainer*> configValues_; //!< A map to link the string of configurable variables with their ConfigValueContainer
     };
 
@@ -173 +178 @@
 
     /**
-        @brief Constructor: Create the ObjectList.
+        @brief Constructor: Creates the ObjectList.
     */
     template <class T>
@@ -182 +187 @@
 
     /**
-        @brief Destructor: Delete the ObjectList, set the singleton-pointer to zero.
+        @brief Destructor: Deletes the ObjectList, sets the singleton-pointer to zero.
     */
     template <class T>
@@ -195 +200 @@
         @param parents An IdentifierList, containing the Identifiers of all parents of the class
         @param name A string, containing exactly the name of the class
-        @param bRootClass True if the class is either an Interface or BaseObject itself
+        @param bRootClass True if the class is either an Interface or the BaseObject itself
         @return The ClassIdentifier itself
     */
@@ -235 +240 @@
 
     /**
-        @returns the Identifier itself
+        @returns the Identifier itself.
     */
     template <class T>
@@ -270 +275 @@
     //! The SubclassIdentifier acts almost like an Identifier, but has some prerequisites.
     /**
-        You can only assign Identifiers that belong to a class of at least B (or derived) to a SubclassIdentifier<T>.
+        You can only assign an Identifier that belongs to a class T (or derived) to a SubclassIdentifier<T>.
         If you assign something else, the program aborts.
         Because we know the minimal type, a dynamic_cast is done, which makes it easier to create a new object.
@@ -323 +328 @@
 
             /**
-                @brief Creates a new object of the type of the assigned identifier and dynamic_casts it to the minimal type given by the SubclassIdentifier.
+                @brief Creates a new object of the type of the assigned Identifier and dynamic_casts it to the minimal type given by T.
                 @return The new object
             */
@@ -330 +335 @@
                 BaseObject* newObject = this->identifier_->fabricate();
 
-                // Check if the creation worked
+                // Check if the creation was successful
                 if (newObject)
                 {

code/branches/objecthierarchy/src/orxonox/core/IdentifierList.cc

@@ -101 +101 @@
 
     /**
-        @returns a string, containing the names of all Identifiers in the list.
+        @returns a string, containing a list of the names of all Identifiers in the list.
     */
     std::string IdentifierList::toString() const

code/branches/objecthierarchy/src/orxonox/core/Iterator.h

@@ -4 +4 @@
 
     The Iterator of a given class allows to iterate through an ObjectList, containing all objects of that type.
-    This is the only way to access the objects in an ObjectList.
+    This is the only way to access the objects stored in an ObjectList.
 
     Usage:
@@ -13 +13 @@
     }
 
-    Warning: Don't delete an object directly through the iterator.
+    Warning: Don't delete objects directly through the iterator.
 */
 
@@ -27 +27 @@
         public:
             /**
-                @brief Constructor: Sets the element whereon the iterator points to zero.
+                @brief Constructor: Sets the element, whereon the iterator points, to zero.
             */
             Iterator()
@@ -35 +35 @@
 
             /**
-                @brief Constructor: Sets the element whereon the iterator points to a given element.
+                @brief Constructor: Sets the element, whereon the iterator points, to a given element.
                 @param element The element to start with
             */
@@ -44 +44 @@
 
             /**
-                @brief Overloading of the ++it operator: Iterator iterates to the next object in the list.
+                @brief Overloading of the ++it operator: Iterator points to the next object in the list.
                 @return The Iterator itself
             */
@@ -54 +54 @@
 
             /**
-                @brief Overloading of the --it operator: Iterator iterates to the previous object in the list.
+                @brief Overloading of the --it operator: Iterator points to the previous object in the list.
                 @return The Iterator itself
             */
@@ -98 +98 @@
             bool operator!=(int compare)
             {
-                // Comparing with something except zero makes no sense
+                // Comparing with anything except zero makes no sense
                 if (compare != 0)
                     std::cout << "Warning: Comparing the " << ClassIdentifier<T>::getIdentifier()->getName() << "-List-Iterator with " << compare << " has no effect. Only comparison with 0 works.\n";
@@ -106 +106 @@
 
         private:
-            ObjectListElement<T>* element_;     //!< The element the Iterator points to
+            ObjectListElement<T>* element_;     //!< The element the Iterator points at
     };
 }

code/branches/objecthierarchy/src/orxonox/core/MetaObjectList.h

@@ -4 +4 @@
 
     The MetaObjectList is a single-linked list, containing all list-elements and their
-    lists wherein the object that owns the MetaObjectList is registered.
-    This allows much faster deleting of objects.
+    lists wherein the object, owning the MetaObjectList, is registered.
+    This allows much faster deletion of objects because no iteration is needed.
 */
 
@@ -20 +20 @@
     {
         public:
-            /** @brief Defaultdestructor */
+            /** @brief Default destructor */
             virtual ~BaseMetaObjectListElement() {};
 
@@ -83 +83 @@
         The MetaObjectList is a single-linked list, containing all list-elements and their
         lists wherein the object that owns the MetaObjectList is registered.
-        This allows much faster deleting of objects.
+        This allows much faster deletion of objects because no iteration is needed.
     */
     class MetaObjectList

code/branches/objecthierarchy/src/orxonox/core/ObjectList.h

@@ -3 +3 @@
     @brief Definition of the ObjectList class.
 
-    The ObjectList is a double-linked list, used by Identifiers to store all objects of a specific class in it.
-    Created objects are added through the RegisterObject-macro in its constructor.
+    The ObjectList is a double-linked list, used by Identifiers to store all objects of a given class.
+    Newly created objects are added through the RegisterObject-macro in its constructor.
     Use Iterator<class> to iterate through all objects of the class.
 */
@@ -32 +32 @@
     /**
         @brief Constructor: Creates the list-element with an object.
-        @param Object The object to store
+        @param object The object to store
     */
     template <class T>
@@ -49 +49 @@
     class Iterator; // Forward declaration
 
-    //! The ObjectList contains all objects of a specific class.
-    /**
-        The ObjectList is used by Identifiers to store all objects of a specific class in it.
+    //! The ObjectList contains all objects of a given class.
+    /**
+        The ObjectList is used by Identifiers to store all objects of a given class.
         Use Iterator<class> to iterate through all objects in the list.
     */
@@ -82 +82 @@
 
     /**
-        @brief Constructor: Sets first_ and last_ to zero and the static member variable pointer_s to _this_
+        @brief Constructor: Sets default values.
     */
     template <class T>

code/branches/objecthierarchy/src/orxonox/core/OrxonoxClass.h

@@ -3 +3 @@
     @brief Definition of the OrxonoxClass Class.
 
-    All objects and interfaces of the game-logic are derived from OrxonoxClass.
-    It stores the Identifier and the MetaObjectList and has all needed functions to create the class-hierarchy.
+    All objects and interfaces of the game-logic (not the engine) are derived from OrxonoxClass.
+    It stores the Identifier and the MetaObjectList and has all needed functions to create and use the class-hierarchy.
 */
 
@@ -17 +17 @@
 namespace orxonox
 {
-    //! The class all objects and interfaces of the game-logic are derived from.
+    //! The class all objects and interfaces of the game-logic (not the engine) are derived from.
     /**
-        BaseObject and Interaces are derived with 'virtual public OrxonoxClass' from OrxonoxClass.
+        The BaseObject and Interaces are derived with 'virtual public OrxonoxClass' from OrxonoxClass.
         OrxonoxClass is needed to create the class-hierarchy at startup and to store the Identifier and the MetaObjectList.
     */
@@ -45 +45 @@
             inline MetaObjectList& getMetaList() { return this->metaList_; }
 
+
+            /** @returns true if the objects class is of the given type or a derivative. */
             inline bool isA(const Identifier* identifier)
                 { return this->getIdentifier()->isA(identifier); }
+            /** @returns true if the objects class is exactly of the given type. */
             inline bool isDirectlyA(const Identifier* identifier)
                 { return this->getIdentifier()->isDirectlyA(identifier); }
+            /** @returns true if the objects class is a child of the given type. */
             inline bool isChildOf(const Identifier* identifier)
                 { return this->getIdentifier()->isChildOf(identifier); }
+            /** @returns true if the objects class is a parent of the given type. */
             inline bool isParentOf(const Identifier* identifier)
                 { return this->getIdentifier()->isParentOf(identifier); }
 
+
+            /** @returns true if the objects class is of the given type or a derivative. */
             inline bool isA(const SubclassIdentifier<class B>* identifier)
                 { return this->getIdentifier()->isA(identifier->getIdentifier()); }
+            /** @returns true if the objects class is exactly of the given type. */
             inline bool isDirectlyA(const SubclassIdentifier<class B>* identifier)
                 { return this->getIdentifier()->isDirectlyA(identifier->getIdentifier()); }
+            /** @returns true if the objects class is a child of the given type. */
             inline bool isChildOf(const SubclassIdentifier<class B>* identifier)
                 { return this->getIdentifier()->isChildOf(identifier->getIdentifier()); }
+            /** @returns true if the objects class is a parent of the given type. */
             inline bool isParentOf(const SubclassIdentifier<class B>* identifier)
                 { return this->getIdentifier()->isParentOf(identifier->getIdentifier()); }
 
+
+            /** @returns true if the objects class is of the given type or a derivative. */
             inline bool isA(const SubclassIdentifier<class B> identifier)
                 { return this->getIdentifier()->isA(identifier.getIdentifier()); }
+            /** @returns true if the objects class is exactly of the given type. */
             inline bool isDirectlyA(const SubclassIdentifier<class B> identifier)
                 { return this->getIdentifier()->isDirectlyA(identifier.getIdentifier()); }
+            /** @returns true if the objects class is a child of the given type. */
             inline bool isChildOf(const SubclassIdentifier<class B> identifier)
                 { return this->getIdentifier()->isChildOf(identifier.getIdentifier()); }
+            /** @returns true if the objects class is a parent of the given type. */
             inline bool isParentOf(const SubclassIdentifier<class B> identifier)
                 { return this->getIdentifier()->isParentOf(identifier.getIdentifier()); }
 
+
+            /** @returns true if the objects class is of the given type or a derivative. */
             inline bool isA(const OrxonoxClass* object)
                 { return this->getIdentifier()->isA(object->getIdentifier()); }
+            /** @returns true if the objects class is exactly of the given type. */
             inline bool isDirectlyA(const OrxonoxClass* object)
                 { return this->getIdentifier()->isDirectlyA(object->getIdentifier()); }
+            /** @returns true if the objects class is a child of the given type. */
             inline bool isChildOf(const OrxonoxClass* object)
                 { return this->getIdentifier()->isChildOf(object->getIdentifier()); }
+            /** @returns true if the objects class is a parent of the given type. */
             inline bool isParentOf(const OrxonoxClass* object)
                 { return this->getIdentifier()->isParentOf(object->getIdentifier()); }
 
 
+            /** @brief Sets the name of the object. @param name The name */
             inline void setName(const std::string& name) { this->name_ = name; }
+
+            /** @returns the name of the object. */
             inline const std::string& getName() const { return this->name_; }
 
+            /** @brief Sets the state of the objects activity. @param bActive True = active */
             inline void setActive(bool bActive) { this->bActive_ = bActive; }
+
+            /** @returns the state of the objects activity. */
             inline const bool isActive() const { return this->bActive_; }
 
+            /** @brief Sets the state of the objects visibility. @param bVisible True = visible */
             inline void setVisible(bool bVisible) { this->bVisible_ = bVisible; }
+
+            /** @returns the state of the objects visibility. */
             inline const bool isVisible() const { return this->bVisible_; }
 
@@ -96 +125 @@
             MetaObjectList metaList_;       //!< MetaObjectList, containing all ObjectLists and ObjectListElements the object is registered in
 
-            std::string name_;
-            bool bActive_;
-            bool bVisible_;
+            std::string name_;              //!< The name of the object
+            bool bActive_;                  //!< True = the object is active
+            bool bVisible_;                 //!< True = the object is visible
     };
 }