Index: /code/branches/FICN/src/orxonox/core/Language.cc
===================================================================
--- /code/branches/FICN/src/orxonox/core/Language.cc	(revision 719)
+++ /code/branches/FICN/src/orxonox/core/Language.cc	(revision 720)
@@ -25,4 +25,9 @@
  *
  */
+
+/*!
+    @file Language.cc
+    @brief Implementation of the Language and the LanguageEntry class.
+*/
 
 #include <fstream>
@@ -36,4 +41,8 @@
     // ###      LanguageEntry      ###
     // ###############################
+    /**
+        @brief Constructor: Sets the default entry.
+        @param fallbackEntry The default entry
+    */
     LanguageEntry::LanguageEntry(const std::string& fallbackEntry)
     {
@@ -41,9 +50,14 @@
 
         this->fallbackEntry_ = fallbackEntry;
-        this->translatedEntry_ = fallbackEntry;
-    }
-
+        this->translatedEntry_ = fallbackEntry; // Set the translation to the fallback entry, for the case that no translation gets assigned
+    }
+
+    /**
+        @brief Sets the translation of the entry.
+        @param translation The translation
+    */
     void LanguageEntry::setTranslation(const std::string& translation)
     {
+        // Check if the translation is more than just an empty string
         if (translation.compare("") != 0)
             this->translatedEntry_ = translation;
@@ -52,6 +66,11 @@
     }
 
+    /**
+        @brief Sets the default entry.
+        @param fallbackEntry The default entry
+    */
     void LanguageEntry::setDefault(const std::string& fallbackEntry)
     {
+        // If the default entry changes and the translation wasn't set yet, use the new default entry as translation
         if (this->translatedEntry_.compare(this->fallbackEntry_) == 0)
             this->translatedEntry_ = fallbackEntry;
@@ -63,23 +82,40 @@
     // ###        Language         ###
     // ###############################
+    /**
+        @brief Constructor: Reads the default language file and sets some values.
+    */
     Language::Language()
     {
         RegisterRootObject(Language);
+
         this->defaultLanguage_ = "default";
         this->defaultTranslation_ = "ERROR: LANGUAGE ENTRY DOESN'T EXIST!";
+
+        // Read the default language file to create all known LanguageEntry objects
         this->readDefaultLanguageFile();
     }
 
+    /**
+        @brief Function to collect the SetConfigValue-macro calls.
+    */
     void Language::setConfigValues()
     {
         SetConfigValue(language_, this->defaultLanguage_).description("The language of the ingame text");
+
+        // Read the translation file after the language was configured
         this->readTranslatedLanguageFile();
     }
 
+    /**
+        @brief Returns a reference to the only existing instance of the Language class and calls the setConfigValues() function.
+        @return The reference to the only existing instance
+    */
     Language& Language::getLanguage()
     {
+        // Use static variables to avoid conflicts while executing this code before main()
         static Language theOnlyLanguageObject = Language();
         static bool bCreatingTheOnlyLanguageObject = true;
 
+        // This workaround is used to set a description of the own config value without creating an infinite recursion
         if (bCreatingTheOnlyLanguageObject)
         {
@@ -91,6 +127,12 @@
     }
 
+    /**
+        @brief Creates a new LanguageEntry with a given name and a given default entry.
+        @param name The name of the entry
+        @param entry The default entry
+    */
     void Language::createEntry(const LanguageEntryName& name, const std::string& entry)
     {
+        // Make sure we don't create a duplicate entry
         if (!this->languageEntries_[name])
         {
@@ -105,17 +147,37 @@
     }
 
+    /**
+        @brief Adds a new LanguageEntry, if it's not already existing.
+        @param name The name of the entry
+        @param entry The default entry
+    */
     void Language::addEntry(const LanguageEntryName& name, const std::string& entry)
     {
         std::map<std::string, LanguageEntry*>::const_iterator it = this->languageEntries_.find(name);
         if (!it->second)
+        {
+            // The entry isn't available yet, meaning it's new, so create it
             this->createEntry(name, entry);
+        }
         else if (it->second->getDefault().compare(entry) == 0)
+        {
+            // The entry is available and the default string is the same, so return because everything is fine
             return;
+        }
         else
+        {
+            // The defined default entry is not the same as in the default language file - change it to the new entry
             it->second->setDefault(entry);
-
+        }
+
+        // Write the default language file because either a new entry was created or an existing entry has changed
         this->writeDefaultLanguageFile();
     }
 
+    /**
+        @brief Returns the translation of a given entry.
+        @param name The name of the entry
+        @return The translation
+    */
     const std::string& Language::getTranslation(const LanguageEntryName& name) const
     {
@@ -125,4 +187,5 @@
         else
         {
+            // Uh, oh, an undefined entry was requested: return the default string
             COUT(2) << "Error: Language entry \"" << name << "\" not found!" << std::endl;
             return this->defaultTranslation_;
@@ -130,4 +193,9 @@
     }
 
+    /**
+        @brief Creates the name of the language file out of the languages name.
+        @param language The name of the language
+        @return The filename
+    */
     const std::string Language::getFileName(const std::string& language)
     {
@@ -135,4 +203,7 @@
     }
 
+    /**
+        @brief Reads the default language file and creates a LanguageEntry objects for every entry.
+    */
     void Language::readDefaultLanguageFile()
     {
@@ -161,8 +232,12 @@
             file.getline(line, 1024);
             std::string lineString = std::string(line);
+
+            // Check if the line is empty
             if (lineString.compare("") != 0)
             {
                 unsigned int pos = lineString.find('=');
-                if (pos < lineString.size() && lineString.size() >= 3)
+
+                // Check if the length is at least 3 and if there's an entry before and behind the =
+                if (pos > 0 && pos < (lineString.size() - 1) && lineString.size() >= 3)
                     this->createEntry(lineString.substr(0, pos), lineString.substr(pos + 1));
                 else
@@ -174,4 +249,7 @@
     }
 
+    /**
+        @brief Reads the language file of the configured language and assigns the translations to the corresponding LanguageEntry object.
+    */
     void Language::readTranslatedLanguageFile()
     {
@@ -197,10 +275,16 @@
             file.getline(line, 1024);
             std::string lineString = std::string(line);
+
+            // Check if the line is empty
             if (lineString.compare("") != 0)
             {
                 unsigned int pos = lineString.find('=');
-                if (pos < lineString.size() && lineString.size() >= 3)
+
+                // Check if the length is at least 3 and if there's an entry before and behind the =
+                if (pos > 0 && pos < (lineString.size() - 1) && lineString.size() >= 3)
                 {
                     std::map<std::string, LanguageEntry*>::const_iterator it = this->languageEntries_.find(lineString.substr(0, pos));
+
+                    // Check if the entry exists
                     if (it->second)
                         it->second->setTranslation(lineString.substr(pos + 1));
@@ -216,4 +300,7 @@
     }
 
+    /**
+        @brief Writes all default entries to the default language file.
+    */
     void Language::writeDefaultLanguageFile() const
     {
Index: /code/branches/FICN/src/orxonox/core/Language.h
===================================================================
--- /code/branches/FICN/src/orxonox/core/Language.h	(revision 719)
+++ /code/branches/FICN/src/orxonox/core/Language.h	(revision 720)
@@ -26,4 +26,20 @@
  */
 
+/*!
+    @file Language.h
+    @brief Definition of the Language and the LanguageEntry class.
+
+    The Language class is used, to get a translation of a string in the configured language.
+    The string is identified by another string, the name of the entry.
+    If the translation in the configured language isn't available, the default entry, defined in the code, is used.
+
+    Usage:
+     - Set the entry with the default string:
+       Language::getLanguage()->addEntry("name of the entry", "the string to translate");
+
+     - Get the translation of the entry in the configured language:
+       std::cout << Language::getLanguage()->getTranslation("name of the entry") << std::endl;
+*/
+
 #ifndef _Language_H__
 #define _Language_H__
@@ -33,5 +49,4 @@
 
 #include "CorePrereqs.h"
-
 #include "OrxonoxClass.h"
 
@@ -40,4 +55,5 @@
     typedef std::string LanguageEntryName;
 
+    //! The LanguageEntry class stores the default- and the translated string of a given entry in the language file.
     class _CoreExport LanguageEntry : public OrxonoxClass
     {
@@ -47,15 +63,18 @@
             void setDefault(const std::string& fallbackEntry);
 
+            /** @brief Returns the translated entry in the configured language. @return The translated entry */
             inline const std::string& getTranslation()
                 { return this->translatedEntry_; }
 
+            /** @brief Returns the default entry. @return The default entry */
             inline const std::string& getDefault()
                 { return this->fallbackEntry_; }
 
         private:
-            std::string fallbackEntry_;
-            std::string translatedEntry_;
+            std::string fallbackEntry_;                             //!< The default entry: Used, if no translation is available or no language configured
+            std::string translatedEntry_;                           //!< The translated entry in the configured language
     };
 
+    //! The Language class manges the language files and entries and stores the LanguageEntry objects in a map.
     class _CoreExport Language : public OrxonoxClass
     {
@@ -77,8 +96,8 @@
             void createEntry(const LanguageEntryName& name, const std::string& entry);
 
-            std::string language_;
-            std::string defaultLanguage_;
-            std::string defaultTranslation_;
-            std::map<std::string, LanguageEntry*> languageEntries_;
+            std::string language_;                                  //!< The configured language
+            std::string defaultLanguage_;                           //!< The default language
+            std::string defaultTranslation_;                        //!< The returned string, if an entry unavailable entry is requested
+            std::map<std::string, LanguageEntry*> languageEntries_; //!< A map to store all LanguageEntry objects and their name
     };
 }
