Index: code/branches/doc/src/libraries/core/ConfigFileManager.h
===================================================================
--- code/branches/doc/src/libraries/core/ConfigFileManager.h	(revision 7363)
+++ code/branches/doc/src/libraries/core/ConfigFileManager.h	(revision 7373)
@@ -30,4 +30,5 @@
     @file
     @ingroup Config ConfigFile
+    @brief Declaration of ConfigFileManager and its helper classes.
 */
 
@@ -51,14 +52,33 @@
     // ConfigFileEntry //
     /////////////////////
+    /**
+        @brief This class represents an entry in the config file.
+
+        This class is pure virtual. Use one of the derived classes to define the type of the entry.
+    */
     class _CoreExport ConfigFileEntry
     {
         public:
+            /// Destructor
             virtual ~ConfigFileEntry() {};
+
+            /// Changes the value of the entry.
             virtual void setValue(const std::string& value) = 0;
+            /// Returns the value of the entry.
             virtual const std::string& getValue() const = 0;
+
+            /// Returns the name of the entry
             virtual const std::string& getName() const = 0;
+
+            /// Changes the comment of the entry (will be placed after the value)
             virtual void setComment(const std::string& comment) = 0;
+
+            /// Returns the index of the entry in a vector (used only if it is a vector)
             virtual unsigned int getIndex() const { return 0; }
+
+            /// Defines if this entry is treated as string which means some special treatment of special characters.
             virtual void setString(bool bString) = 0;
+
+            /// Returns the line as it will be stored in the config file.
             virtual const std::string& getFileEntry() const = 0;
     };
@@ -68,7 +88,18 @@
     // ConfigFileEntryValue //
     //////////////////////////
+    /**
+        @brief This class represents a normal value in the config file.
+    */
     class _CoreExport ConfigFileEntryValue : public ConfigFileEntry
     {
         public:
+            /**
+                @brief Constructor: Initializes the entry.
+
+                @param name                 The name of the entry
+                @param value                The value of the entry
+                @param bString              If true, the value is treated as string which means some special treatment of special characters.
+                @param additionalComment    An optional comment that will be placed behind the value in the config file
+            */
             inline ConfigFileEntryValue(const std::string& name, const std::string& value = "", bool bString = false, const std::string& additionalComment = "")
                 : name_(name)
@@ -78,4 +109,5 @@
                 { this->update(); }
 
+            /// Destructor
             inline virtual ~ConfigFileEntryValue() {}
 
@@ -97,4 +129,5 @@
                 { return this->fileEntry_; }
 
+            /// Returns the "key" of the value (in this case it's just the name of the entry, but for vectors it's different)
             inline virtual const std::string& getKeyString() const
                 { return this->name_; }
@@ -103,9 +136,9 @@
             virtual void update();
 
-            const std::string name_;
-            std::string value_;
-            std::string additionalComment_;
-            std::string fileEntry_;
-            bool bString_;
+            const std::string name_;            ///< The name of the value
+            std::string value_;                 ///< The value
+            std::string additionalComment_;     ///< The additional comment
+            std::string fileEntry_;             ///< The string as it will be stored in the config file
+            bool bString_;                      ///< If true, the value is treated as string which means some special treatment of special characters.
     };
 
@@ -114,7 +147,19 @@
     // ConfigFileEntryVectorValue //
     ////////////////////////////////
+    /**
+        @brief Subclass of ConfigFileEntryValue, represents an element of a vector.
+    */
     class _CoreExport ConfigFileEntryVectorValue : public ConfigFileEntryValue
     {
         public:
+            /**
+                @brief Constructor: Initializes the entry.
+
+                @param name                 The name of the vector
+                @param index                The index of the element in the vector
+                @param value                The value of the element
+                @param bString              If true, the value is treated as string which means some special treatment of special characters.
+                @param additionalComment    An optional comment that will be placed behind the value in the config file
+            */
             inline ConfigFileEntryVectorValue(const std::string& name, unsigned int index, const std::string& value = "", bool bString = false, const std::string& additionalComment = "")
                 : ConfigFileEntryValue(name, value, bString, additionalComment)
@@ -122,4 +167,5 @@
                 { this->update(); /*No virtual calls in base class ctor*/ }
 
+            /// Destructor
             inline ~ConfigFileEntryVectorValue() {}
 
@@ -127,4 +173,5 @@
                 { return this->index_; }
 
+            /// Returns the "key" of the value (the name of the vector plus the index of the element)
             inline const std::string& getKeyString() const
                 { return this->keyString_; }
@@ -133,6 +180,6 @@
             void update();
 
-            unsigned int index_;
-            std::string keyString_;
+            unsigned int index_;        ///< The index of the element in the vector
+            std::string keyString_;     ///< The full name of the entry (the name of the vector plus the index of the element)
     };
 
@@ -141,8 +188,14 @@
     // ConfigFileEntryComment //
     ////////////////////////////
+    /**
+        @brief This class represents a line in the config file which contains only a comment.
+    */
     class _CoreExport ConfigFileEntryComment : public ConfigFileEntry
     {
         public:
+            /// Constructor: Initializes the object.
             inline ConfigFileEntryComment(const std::string& comment) : comment_(comment) {}
+
+            /// Destructor
             inline virtual ~ConfigFileEntryComment() {}
 
@@ -164,9 +217,6 @@
                 { return this->comment_; }
 
-            inline virtual const std::string& getKeyString() const
-                { return BLANKSTRING; }
-
         private:
-            std::string comment_;
+            std::string comment_;   ///< The comment
     };
 
@@ -175,4 +225,9 @@
     // ConfigFileSection //
     ///////////////////////
+    /**
+        @brief Represents a section in a config file.
+
+        A section has a name and a list of config values.
+    */
     class _CoreExport ConfigFileSection
     {
@@ -181,4 +236,10 @@
 
         public:
+            /**
+                @brief Constructor: Initializes the section.
+
+                @param name The name of the section
+                @param additionalComment An additional comment placed after the title of the section in the config file
+            */
             inline ConfigFileSection(const std::string& name, const std::string& additionalComment = "")
                 : name_(name)
@@ -188,12 +249,27 @@
             ~ConfigFileSection();
 
+            /// Returns the name of the section.
             inline const std::string& getName() const
                 { return this->name_; }
 
+            /// Changes the comment which is placed after the title of the section in the config file.
             inline void setComment(const std::string& comment)
                 { this->additionalComment_ = comment; }
 
+            /**
+                @brief Stores a value in the section. If the entry doesn't exist, it's created.
+
+                @param name     The name of the entry
+                @param value    The new value
+                @param bString  If true, the value is treated as string which means some special treatment of special characters.
+            */
             inline void setValue(const std::string& name, const std::string& value, bool bString)
                 { this->getOrCreateEntry(name, value, bString)->setValue(value); }
+            /**
+                @brief Returns the value of a given entry in the section. Returns a blank string if the value doesn't exist.
+
+                @param name     The name of the entry
+                @param bString  If true, the value is treated as string which means some special treatment of special characters.
+            */
             inline const std::string& getValue(const std::string& name, bool bString)
             {
@@ -201,14 +277,36 @@
                 if (entry)
                 {
-                    entry->setString(bString);
+                    entry->setString(bString);  // if the entry was loaded from the config file, we have to tell it if it's a string
                     return entry->getValue();
                 }
                 return BLANKSTRING;
             }
+            /**
+                @brief Returns the value of a given entry in the section. If it doesn't exist, the entry is created using the fallback value.
+
+                @param name     The name of the entry
+                @param fallback The value that will be used if the entry doesn't exist
+                @param bString  If true, the value is treated as string which means some special treatment of special characters.
+            */
             inline const std::string& getOrCreateValue(const std::string& name, const std::string& fallback, bool bString)
                 { return this->getOrCreateEntry(name, fallback, bString)->getValue(); }
 
+            /**
+                @brief Stores the value of an element of a vector in the section. If the entry doesn't exist, it's created.
+
+                @param name     The name of the vector
+                @param index    The index of the element in the vector
+                @param value    The new value
+                @param bString  If true, the value is treated as string which means some special treatment of special characters.
+            */
             inline void setValue(const std::string& name, unsigned int index, const std::string& value, bool bString)
                 { this->getOrCreateEntry(name, index, value, bString)->setValue(value); }
+            /**
+                @brief Returns the value of a given element of a vector in the section. Returns a blank string if the value doesn't exist.
+
+                @param name     The name of the vector
+                @param index    The index of the element in the vector
+                @param bString  If true, the value is treated as string which means some special treatment of special characters.
+            */
             inline const std::string& getValue(const std::string& name, unsigned int index, bool bString)
             {
@@ -216,9 +314,17 @@
                 if (entry)
                 {
-                    entry->setString(bString);
+                    entry->setString(bString);  // if the entry was loaded from the config file, we have to tell it if it's a string
                     return entry->getValue();
                 }
                 return BLANKSTRING;
             }
+            /**
+                @brief Returns the value of a given element of a vector in the section. If it doesn't exist, the entry is created using the fallback value.
+
+                @param name     The name of the vector
+                @param index    The index of the element in the vector
+                @param fallback The value that will be used if the entry doesn't exist
+                @param bString  If true, the value is treated as string which means some special treatment of special characters.
+            */
             inline const std::string& getOrCreateValue(const std::string& name, unsigned int index, const std::string& fallback, bool bString)
                 { return this->getOrCreateEntry(name, index, fallback, bString)->getValue(); }
@@ -230,8 +336,11 @@
 
         private:
+            /// Returns the list of entries in this section.
             std::list<ConfigFileEntry*>& getEntries()
                 { return this->entries_; }
+            /// Returns the begin-iterator of the list of entries in this section.
             std::list<ConfigFileEntry*>::const_iterator getEntriesBegin() const
                 { return this->entries_.begin(); }
+            /// Returns the end-iterator of the list of entries in this section.
             std::list<ConfigFileEntry*>::const_iterator getEntriesEnd() const
                 { return this->entries_.end(); }
@@ -241,14 +350,30 @@
 
             ConfigFileEntry* getEntry(const std::string& name) const;
+            /**
+                @brief Returns the entry with given name. If it doesn't exist, the entry is created using the fallback value.
+
+                @param name     The name of the entry
+                @param fallback The value that will be used if the entry doesn't exist
+                @param bString  If true, the value is treated as string which means some special treatment of special characters.
+            */
             inline ConfigFileEntry* getOrCreateEntry(const std::string& name, const std::string& fallback, bool bString)
                 { return (*this->getOrCreateEntryIterator(name, fallback, bString)); }
+
             ConfigFileEntry* getEntry(const std::string& name, unsigned int index) const;
+            /**
+                @brief Returns the entry that contains an element of a vector with given name. If it doesn't exist, the entry is created using the fallback value.
+
+                @param name     The name of the entry
+                @param index    The index of the element in the vector
+                @param fallback The value that will be used if the entry doesn't exist
+                @param bString  If true, the value is treated as string which means some special treatment of special characters.
+            */
             inline ConfigFileEntry* getOrCreateEntry(const std::string& name, unsigned int index, const std::string& fallback, bool bString)
                 { return (*this->getOrCreateEntryIterator(name, index, fallback, bString)); }
 
-            std::string name_;
-            std::string additionalComment_;
-            std::list<ConfigFileEntry*> entries_;
-            bool bUpdated_;
+            std::string name_;                      ///< The name of the section
+            std::string additionalComment_;         ///< The additional comment which is placed after the title of the section in the config file
+            std::list<ConfigFileEntry*> entries_;   ///< The list of entries in this section
+            bool bUpdated_;                         ///< True if an entry is created
     };
 
@@ -257,4 +382,9 @@
     // ConfigFile //
     ////////////////
+    /**
+        @brief This class represents a config file, which is stored on the hard-disk and contains config values in different sections.
+
+        It provides an interface to manipulate the sections and values.
+    */
     class _CoreExport ConfigFile
     {
@@ -268,7 +398,16 @@
             virtual void clear();
 
+            /// Returns the file-name of this config file
             inline const std::string& getFilename()
                 { return this->filename_; }
 
+            /**
+                @brief Stores a value in the config file. If the entry or its section doesn't exist, it's created.
+
+                @param section  The name of the section
+                @param name     The name of the entry
+                @param value    The new value
+                @param bString  If true, the value is treated as string which means some special treatment of special characters.
+            */
             inline void setValue(const std::string& section, const std::string& name, const std::string& value, bool bString)
             {
@@ -276,4 +415,11 @@
                 this->save();
             }
+            /**
+                @brief Returns the value of a given entry in the config file. Returns a blank string if the value doesn't exist.
+
+                @param section  The name of the section
+                @param name     The name of the entry
+                @param bString  If true, the value is treated as string which means some special treatment of special characters.
+            */
             inline const std::string& getValue(const std::string& section, const std::string& name, bool bString)
             {
@@ -281,6 +427,28 @@
                 return (sectionPtr ? sectionPtr->getValue(name, bString) : BLANKSTRING);
             }
-            const std::string& getOrCreateValue(const std::string& section, const std::string& name, const std::string& fallback, bool bString);
-
+            /**
+                @brief Returns the value of a given entry in the config file. If it doesn't exist, the entry is created using the fallback value.
+
+                @param section  The name of the section
+                @param name     The name of the entry
+                @param fallback The value that will be used if the entry doesn't exist
+                @param bString  If true, the value is treated as string which means some special treatment of special characters.
+            */
+            inline const std::string& getOrCreateValue(const std::string& section, const std::string& name, const std::string& fallback, bool bString)
+            {
+                const std::string& output = this->getOrCreateSection(section)->getOrCreateValue(name, fallback, bString);
+                this->saveIfUpdated();
+                return output;
+            }
+
+            /**
+                @brief Stores the value of an element of a vector in the config file. If the entry or its section doesn't exist, it's created.
+
+                @param section  The name of the section
+                @param name     The name of the vector
+                @param index    The index of the element in the vector
+                @param value    The new value
+                @param bString  If true, the value is treated as string which means some special treatment of special characters.
+            */
             inline void setValue(const std::string& section, const std::string& name, unsigned int index, const std::string& value, bool bString)
             {
@@ -288,4 +456,12 @@
                 this->save();
             }
+            /**
+                @brief Returns the value of a given element of a vector in the config file. Returns a blank string if the value doesn't exist.
+
+                @param section  The name of the section
+                @param name     The name of the vector
+                @param index    The index of the element in the vector
+                @param bString  If true, the value is treated as string which means some special treatment of special characters.
+            */
             inline const std::string& getValue(const std::string& section, const std::string& name, unsigned int index, bool bString)
             {
@@ -293,7 +469,26 @@
                 return (sectionPtr ? sectionPtr->getValue(name, index, bString) : BLANKSTRING);
             }
-            const std::string& getOrCreateValue(const std::string& section, const std::string& name, unsigned int index, const std::string& fallback, bool bString);
+            /**
+                @brief Returns the value of a given element of a vector in the config file. If it doesn't exist, the entry is created using the fallback value.
+
+                @param section  The name of the section
+                @param name     The name of the vector
+                @param index    The index of the element in the vector
+                @param fallback The value that will be used if the entry doesn't exist
+                @param bString  If true, the value is treated as string which means some special treatment of special characters.
+            */
+            const std::string& getOrCreateValue(const std::string& section, const std::string& name, unsigned int index, const std::string& fallback, bool bString)
+            {
+                const std::string& output = this->getOrCreateSection(section)->getOrCreateValue(name, index, fallback, bString);
+                this->saveIfUpdated();
+                return output;
+            }
 
             void deleteVectorEntries(const std::string& section, const std::string& name, unsigned int startindex = 0);
+            /**
+                @brief Returns the size of a config vector.
+                @param section  The section of the vector
+                @param name     The name of the vector
+            */
             inline unsigned int getVectorSize(const std::string& section, const std::string& name) const
             {
@@ -302,5 +497,5 @@
             }
 
-            static const char* DEFAULT_CONFIG_FOLDER;
+            static const char* DEFAULT_CONFIG_FOLDER;   ///< The folder where the default config files will be stored
 
         protected:
@@ -308,11 +503,12 @@
             ConfigFileSection* getOrCreateSection(const std::string& section);
 
-            std::list<ConfigFileSection*> sections_;
+            std::list<ConfigFileSection*> sections_;    ///< A list of sections in this config file
 
         private:
             void saveIfUpdated();
-            const std::string filename_;
-            const bool bCopyFallbackFile_;
-            bool bUpdated_;
+
+            const std::string filename_;                ///< The filename of this config file
+            const bool bCopyFallbackFile_;              ///< If true, the default config file is copied into the config-directory before loading the file
+            bool bUpdated_;                             ///< Becomes true if a section is added
     };
 
@@ -321,4 +517,13 @@
     // SettingsConfigFile //
     ////////////////////////
+    /**
+        @brief Child class of ConfigFile, used to store the settings of the game.
+
+        In addition to ConfigFile, this class provides an interface to manipulate the settings
+        with console commands and to cache entries in instances of ConfigValueContainer.
+
+        SettingsConfigFile is a Singleton, meaning there's only one instance of this class
+        (and thus only one config file that stores settings).
+    */
     class _CoreExport SettingsConfigFile // tolua_export
         : public ConfigFile, public Singleton<SettingsConfigFile>
@@ -343,8 +548,11 @@
             void removeConfigValueContainer(ConfigValueContainer* container);
 
+            /// Returns a set containing the names of all sections in this config file.
             inline const std::set<std::string>& getSectionNames()
                 { return this->sectionNames_; }
+            /// Returns the lower-bound-iterator of the @ref ConfigValueContainer "config value containers" for the given section.
             inline ContainerMap::const_iterator getContainerLowerBound(const std::string section)
                 { return this->containers_.lower_bound(section); }
+            /// Returns the upper-bound-iterator of the @ref ConfigValueContainer "config value containers" for the given section.
             inline ContainerMap::const_iterator getContainerUpperBound(const std::string section)
                 { return this->containers_.upper_bound(section); }
@@ -356,7 +564,7 @@
             bool configImpl(const std::string& section, const std::string& entry, const std::string& value, bool (ConfigValueContainer::*function)(const MultiType&));
 
-            ContainerMap containers_;
-            std::set<std::string> sectionNames_;
-            static SettingsConfigFile* singletonPtr_s;
+            ContainerMap containers_;                   ///< Stores all @ref ConfigValueContainer "config value containers"
+            std::set<std::string> sectionNames_;        ///< Stores all section names
+            static SettingsConfigFile* singletonPtr_s;  ///< The singleton pointer
     }; // tolua_export
 
@@ -365,4 +573,7 @@
     // ConfigFileManager //
     ///////////////////////
+    /**
+        @brief Manages the different config files (settings, calibration, etc). Implemented as Singleton.
+    */
     class _CoreExport ConfigFileManager : public Singleton<ConfigFileManager>
     {
@@ -374,4 +585,5 @@
             void setFilename(ConfigFileType::Value type, const std::string& filename);
 
+            /// Returns the config file of a given type (settings, calibration, etc.)
             inline ConfigFile* getConfigFile(ConfigFileType::Value type)
             {
@@ -381,8 +593,8 @@
 
         private:
-            ConfigFileManager(const ConfigFileManager&);
-
-            boost::array<ConfigFile*, 3> configFiles_;
-            static ConfigFileManager* singletonPtr_s;
+            ConfigFileManager(const ConfigFileManager&);    ///< Copy-constructor: not implemented
+
+            boost::array<ConfigFile*, 3> configFiles_;      ///< Stores the config files for each type in an array (must have the same size like ConfigFileType::Value)
+            static ConfigFileManager* singletonPtr_s;       ///< Stores the singleton-pointer
     };
 } // tolua_export
