Index: code/trunk/src/libraries/core/command/Shell.cc
===================================================================
--- code/trunk/src/libraries/core/command/Shell.cc	(revision 7284)
+++ code/trunk/src/libraries/core/command/Shell.cc	(revision 7401)
@@ -26,4 +26,9 @@
  *
  */
+
+/**
+    @file
+    @brief Implementation of the Shell class.
+*/
 
 #include "Shell.h"
@@ -48,4 +53,9 @@
     unsigned int Shell::cacheSize_s;
 
+    /**
+        @brief Constructor: Initializes the values and registers itself at OutputHandler.
+        @param consoleName The name of the shell - used to define the name of the soft-debug-level config-value
+        @param bScrollable If true, the user is allowed to scroll through the output-lines
+    */
     Shell::Shell(const std::string& consoleName, bool bScrollable)
         : OutputListener(consoleName)
@@ -88,4 +98,7 @@
     }
 
+    /**
+        @brief Destructor: Unregisters the shell from OutputHandler.
+    */
     Shell::~Shell()
     {
@@ -94,4 +107,7 @@
     }
 
+    /**
+        @brief Defines the config values.
+    */
     void Shell::setConfigValues()
     {
@@ -113,4 +129,7 @@
     }
 
+    /**
+        @brief Config-value callback: Called when the history offset has changed in the config-file.
+    */
     void Shell::commandHistoryOffsetChanged()
     {
@@ -119,4 +138,7 @@
     }
 
+    /**
+        @brief Config-value callback: Called when the length of the command history has changed in the config-file.
+    */
     void Shell::commandHistoryLengthChanged()
     {
@@ -131,4 +153,7 @@
     }
 
+    /**
+        @brief Registers this object as listener for different key-events at the input buffer.
+    */
     void Shell::configureInputBuffer()
     {
@@ -159,16 +184,7 @@
     }
 
-    /*
-    void Shell::history()
-    {
-        Shell& instance = Shell::getInstance();
-
-        for (unsigned int i = instance.historyOffset_; i < instance.commandHistory_.size(); ++i)
-            instance.addOutput(instance.commandHistory_[i] + '\n', -1);
-        for (unsigned int i =  0; i < instance.historyOffset_; ++i)
-            instance.addOutput(instance.commandHistory_[i] + '\n', -1);
-    }
-    */
-
+    /**
+        @brief Registers a shell listener which listens for changes in this shell.
+    */
     void Shell::registerListener(ShellListener* listener)
     {
@@ -176,4 +192,7 @@
     }
 
+    /**
+        @brief Unregisters a shell listener.
+    */
     void Shell::unregisterListener(ShellListener* listener)
     {
@@ -187,4 +206,7 @@
     }
 
+    /**
+        @brief Changes the position of the cursor in the input buffer.
+    */
     void Shell::setCursorPosition(unsigned int cursor)
     {
@@ -193,4 +215,7 @@
     }
 
+    /**
+        @brief Sends output to the internal output buffer.
+    */
     void Shell::addOutput(const std::string& text, LineType type)
     {
@@ -199,4 +224,7 @@
     }
 
+    /**
+        @brief Clears the list of output-lines.
+    */
     void Shell::clearOutput()
     {
@@ -210,4 +238,7 @@
     }
 
+    /**
+        @brief Returns an iterator to the newest line of output (except if the user is currently scrolling through the output).
+    */
     Shell::LineList::const_iterator Shell::getNewestLineIterator() const
     {
@@ -218,4 +249,7 @@
     }
 
+    /**
+        @brief Returns the end() iterator of the list of output-lines.
+    */
     Shell::LineList::const_iterator Shell::getEndIterator() const
     {
@@ -223,4 +257,7 @@
     }
 
+    /**
+        @brief Adds a command to the history of entered commands and writes it to the config-file.
+    */
     void Shell::addToHistory(const std::string& command)
     {
@@ -237,4 +274,7 @@
     }
 
+    /**
+        @brief Returns a command from the history of entered commands (usually the most recent history entry, but the user can scroll through the history).
+    */
     const std::string& Shell::getFromHistory() const
     {
@@ -246,4 +286,7 @@
     }
 
+    /**
+        @brief Called by OutputHandler or internally whenever output was sent to the output buffer. Reads from the buffer and writes the new output-lines to the list.
+    */
     void Shell::outputChanged(int lineType)
     {
@@ -251,28 +294,34 @@
         do
         {
+            // get the first line from the buffer
             std::string output;
             std::getline(this->outputBuffer_, output);
 
+            // check the state of the buffer
             bool eof = this->outputBuffer_.eof();
             bool fail = this->outputBuffer_.fail();
             if (eof)
-                this->outputBuffer_.flush();
+                this->outputBuffer_.flush(); // check if more output was received in the meantime
             if (eof || fail)
-                this->outputBuffer_.clear();
+                this->outputBuffer_.clear(); // clear the error flags
+
+            // the line is terminated with a line-break if neither an error occurred nor the end of the file was reached
             newline = (!eof && !fail);
 
+            // no output retrieved - break the loop
             if (!newline && output.empty())
                 break;
 
+            // check if the last line was terminated with a line-break
             if (this->bFinishedLastLine_)
             {
+                // yes it was - push the new line to the list
                 this->outputLines_.push_front(std::make_pair(output, static_cast<LineType>(lineType)));
 
+                // adjust the scroll position if needed
                 if (this->scrollPosition_)
                     this->scrollPosition_++;
                 else
                     this->scrollIterator_ = this->outputLines_.begin();
-
-                this->bFinishedLastLine_ = newline;
 
                 if (!this->scrollPosition_)
@@ -281,13 +330,18 @@
             else
             {
+                // no it wasn't - add the new output to the last line
                 this->outputLines_.front().first += output;
-                this->bFinishedLastLine_ = newline;
                 this->updateListeners<&ShellListener::onlyLastLineChanged>();
             }
+
+            // remember if the last line was terminated with a line-break
             this->bFinishedLastLine_ = newline;
 
-        } while (newline);
-    }
-
+        } while (newline); // loop as long as more lines are in the buffer
+    }
+
+    /**
+        @brief Clears the text in the input buffer.
+    */
     void Shell::clearInput()
     {
@@ -298,8 +352,4 @@
     }
 
-    void Shell::setPromptPrefix(const std::string& str)
-    {
-    }
-
 
     // ##########################################
@@ -307,4 +357,5 @@
     // ##########################################
 
+    /// InputBuffer callback: Called if the input changes.
     void Shell::inputChanged()
     {
@@ -313,4 +364,5 @@
     }
 
+    /// InputBuffer callback: Called if a key was pressed that executes a command (usually [return]).
     void Shell::execute()
     {
@@ -340,4 +392,5 @@
     }
 
+    /// InputBuffer callback: Called if a key was pressed that shows hints and completes a command (usually [tab]).
     void Shell::hintAndComplete()
     {
@@ -349,4 +402,5 @@
     }
 
+    /// InputBuffer callback: Called if a key was pressed that deletes the character before the cursor (usually [backspace]).
     void Shell::backspace()
     {
@@ -356,19 +410,5 @@
     }
 
-    void Shell::exit()
-    {
-        if (this->inputBuffer_->getSize() > 0)
-        {
-            this->clearInput();
-            return;
-        }
-
-        this->clearInput();
-        this->scrollPosition_ = 0;
-        this->scrollIterator_ = this->outputLines_.begin();
-
-        this->updateListeners<&ShellListener::exit>();
-    }
-
+    /// InputBuffer callback: Called if a key was pressed that deletes the character after the cursor (usually [delete]).
     void Shell::deleteChar()
     {
@@ -377,4 +417,5 @@
     }
 
+    /// InputBuffer callback: Called if a key was pressed that moves the input cursor the right (usually [arrow right]).
     void Shell::cursorRight()
     {
@@ -383,4 +424,5 @@
     }
 
+    /// InputBuffer callback: Called if a key was pressed that moves the input cursor the left (usually [arrow left]).
     void Shell::cursorLeft()
     {
@@ -389,4 +431,5 @@
     }
 
+    /// InputBuffer callback: Called if a key was pressed that moves the input cursor the end of the input line (usually [end]).
     void Shell::cursorEnd()
     {
@@ -395,4 +438,5 @@
     }
 
+    /// InputBuffer callback: Called if a key was pressed that moves the input cursor the beginning of the input line (usually [home]).
     void Shell::cursorHome()
     {
@@ -401,4 +445,5 @@
     }
 
+    /// InputBuffer callback: Called if a key was pressed that scrolls upwards through the history of entered commands (usually [arrow up]).
     void Shell::historyUp()
     {
@@ -410,4 +455,5 @@
     }
 
+    /// InputBuffer callback: Called if a key was pressed that scrolls downwards through the history of entered commands (usually [arrow down]).
     void Shell::historyDown()
     {
@@ -419,4 +465,5 @@
     }
 
+    /// InputBuffer callback: Called if a key was pressed that searches upwards through the history for a command stat starts like the one the user is currently typing (usually [page up]). Only if the shell is not scrollable.
     void Shell::historySearchUp()
     {
@@ -437,4 +484,5 @@
     }
 
+    /// InputBuffer callback: Called if a key was pressed that searches downwards through the history for a command stat starts like the one the user is currently typing (usually [page down]). Only if the shell is not scrollable.
     void Shell::historySearchDown()
     {
@@ -455,4 +503,5 @@
     }
 
+    /// InputBuffer callback: Called if a key was pressed that scrolls upwards through the output history (usually [page up]). Only if the shell is scrollable.
     void Shell::scrollUp()
     {
@@ -466,4 +515,5 @@
     }
 
+    /// InputBuffer callback: Called if a key was pressed that scrolls downwards through the output history (usually [page down]). Only if the shell is scrollable.
     void Shell::scrollDown()
     {
@@ -476,3 +526,19 @@
         }
     }
+
+    /// InputBuffer callback: Called if a key was pressed that clears the text in the input buffer or closes the shell (usually [esc]).
+    void Shell::exit()
+    {
+        if (this->inputBuffer_->getSize() > 0)
+        {
+            this->clearInput();
+            return;
+        }
+
+        this->clearInput();
+        this->scrollPosition_ = 0;
+        this->scrollIterator_ = this->outputLines_.begin();
+
+        this->updateListeners<&ShellListener::exit>();
+    }
 }
