Changeset 7361 for code/branches/doc/src/libraries/core

Timestamp:

Sep 5, 2010, 10:51:55 PM (14 years ago)

Author:

landauf

Message:

added documentation

Location:

code/branches/doc/src/libraries/core

Files:

• CommandLineParser.h (modified) (1 diff)
• command/IOConsole.h (modified) (1 diff)
• command/IOConsolePOSIX.h (modified) (1 diff)
• command/IOConsoleWindows.h (modified) (1 diff)
• command/IRC.cc (modified) (12 diffs)
• command/IRC.h (modified) (3 diffs)
• command/Shell.cc (modified) (36 diffs)
• command/Shell.h (modified) (7 diffs)
• command/TclBind.cc (modified) (12 diffs)
• command/TclBind.h (modified) (4 diffs)
• command/TclThreadList.h (modified) (2 diffs)
• command/TclThreadManager.cc (modified) (2 diffs)
• command/TclThreadManager.h (modified) (1 diff)

code/branches/doc/src/libraries/core/CommandLineParser.h

@@ -26 +26 @@
  *
  */
+
+/**
+    @defgroup CmdArgs Commandline Arguments
+    @ingroup Config
+    @brief For a reference of all commandline arguments see @ref cmdargspage
+*/
+
+/**
+    @file
+    @ingroup Config CmdArgs
+*/
 
 #ifndef _CommandLine_H__

code/branches/doc/src/libraries/core/command/IOConsole.h

@@ -27 +27 @@
  */
 
+/**
+    @file
+    @ingroup Command ShellConsole
+*/
+
 #include "OrxonoxConfig.h"
 

code/branches/doc/src/libraries/core/command/IOConsolePOSIX.h

@@ -27 +27 @@
  *
  */
+
+/**
+    @file
+    @ingroup Command ShellConsole
+*/
 
 #ifndef _IOConsole_H__

code/branches/doc/src/libraries/core/command/IOConsoleWindows.h

@@ -26 +26 @@
  *
  */
+
+/**
+    @file
+    @ingroup Command ShellConsole
+*/
 
 #ifndef _IOConsole_H__

code/branches/doc/src/libraries/core/command/IRC.cc

@@ -27 +27 @@
  */
 
+/**
+    @file
+    @brief Implementation of the IRC class and the IRC console commands.
+*/
+
 #include "IRC.h"
 
@@ -39 +44 @@
 namespace orxonox
 {
-    static const unsigned int IRC_TCL_THREADID  = 1421421421;
+    static const unsigned int IRC_TCL_THREADID  = 1421421421;   ///< The ID of the thread in TclThreadManager that is used for the IRC connection
 
     SetConsoleCommand("IRC", "say",  &IRC::say);
@@ -45 +50 @@
     SetConsoleCommand("IRC", "nick", &IRC::nick);
 
+    /**
+        @brief Returns the only existing instance of IRC.
+    */
+    IRC& IRC::getInstance()
+    {
+        static IRC instance;
+        return instance;
+    }
+
+    /**
+        @brief Constructor: Doesn't yet connect to IRC nor does it create a Tcl interpreter.
+        The IRC object will automatically connect to the IRC server if one of the registered
+        console commands is used the first time.
+    */
     IRC::IRC()
     {
@@ -50 +69 @@
     }
 
+    /**
+        @brief Creates and initializes a new multithreaded Tcl-interpreter and defines some callbacks to display IRC-messages in the console.
+    */
     void IRC::initialize()
     {
@@ -70 +92 @@
     }
 
-    IRC& IRC::getInstance()
-    {
-        static IRC instance;
-        return instance;
-    }
-
+    /**
+        @brief Executes a Tcl-command on the Tcl-interpreter.
+    */
     bool IRC::eval(const std::string& command)
     {
@@ -96 +115 @@
     }
 
+    /// Console command: Sends a message to the current channel on the IRC server.
     void IRC::say(const std::string& message)
     {
@@ -102 +122 @@
     }
 
+    /// Console command: Sends a message to a given channel or nickname on the IRC server.
     void IRC::msg(const std::string& channel, const std::string& message)
     {
@@ -108 +129 @@
     }
 
+    /// Console command: Changes the nickname on the IRC server.
     void IRC::nick(const std::string& nickname)
     {
@@ -114 +136 @@
     }
 
+    /// Tcl-callback: Prints a message that was received from the current IRC channel to the console.
     void IRC::tcl_say(Tcl::object const &channel, Tcl::object const &nick, Tcl::object const &args)
     {
@@ -119 +142 @@
     }
 
+    /// Tcl-callback: Prints a private message that was received from a user to the console.
     void IRC::tcl_privmsg(Tcl::object const &query, Tcl::object const &nick, Tcl::object const &args)
     {
@@ -124 +148 @@
     }
 
+    /// Tcl-callback: Prints an action-message (usually /me ...) that was received from the current IRC channel to the console.
     void IRC::tcl_action(Tcl::object const &channel, Tcl::object const &nick, Tcl::object const &args)
     {
@@ -129 +154 @@
     }
 
+    /// Tcl-callback: Prints all kinds of information that were received from the IRC server or channel (connection info, join, part, modes, ...) to the console.
     void IRC::tcl_info(Tcl::object const &channel, Tcl::object const &args)
     {

code/branches/doc/src/libraries/core/command/IRC.h

@@ -27 +27 @@
  */
 
+/**
+    @file
+    @ingroup Command Tcl
+    @brief Declaration of IRC helper class, used for IRC connections using Tcl.
+*/
+
 #ifndef _IRC_H__
 #define _IRC_H__
@@ -36 +42 @@
 namespace orxonox
 {
+    /**
+        @brief The IRC class creates a Tcl-thread (see TclThreadManager) and connects to an IRC server.
+        It provides different console commands to send messages and to perform other actions on the IRC server.
+    */
     class _CoreExport IRC
     {
@@ -55 +65 @@
 
             IRC();
-            IRC(const IRC& other);
-            ~IRC() {}
+            IRC(const IRC& other);              ///< Copy-constructor: Not implemented
+            ~IRC() {}                           ///< Destructor
 
-            Tcl::interpreter* interpreter_;
-            std::string nickname_;
+            Tcl::interpreter* interpreter_;     ///< The Tcl interpreter that is used for the IRC connection
+            std::string nickname_;              ///< The user's nickname on the IRC server
     };
 }

code/branches/doc/src/libraries/core/command/Shell.cc

@@ -26 +26 @@
  *
  */
+
+/**
+    @file
+    @brief Implementation of the Shell class.
+*/
 
 #include "Shell.h"
@@ -48 +53 @@
     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 +98 @@
     }
 
+    /**
+        @brief Destructor: Unregisters the shell from OutputHandler.
+    */
     Shell::~Shell()
     {
@@ -94 +107 @@
     }
 
+    /**
+        @brief Defines the config values.
+    */
     void Shell::setConfigValues()
     {
@@ -113 +129 @@
     }
 
+    /**
+        @brief Config-value callback: Called when the history offset has changed in the config-file.
+    */
     void Shell::commandHistoryOffsetChanged()
     {
@@ -119 +138 @@
     }
 
+    /**
+        @brief Config-value callback: Called when the length of the command history has changed in the config-file.
+    */
     void Shell::commandHistoryLengthChanged()
     {
@@ -131 +153 @@
     }
 
+    /**
+        @brief Registers this object as listener for different key-events at the input buffer.
+    */
     void Shell::configureInputBuffer()
     {
@@ -159 +184 @@
     }
 
-    /*
-    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 +192 @@
     }
 
+    /**
+        @brief Unregisters a shell listener.
+    */
     void Shell::unregisterListener(ShellListener* listener)
     {
@@ -187 +206 @@
     }
 
+    /**
+        @brief Changes the position of the cursor in the input buffer.
+    */
     void Shell::setCursorPosition(unsigned int cursor)
     {
@@ -193 +215 @@
     }
 
+    /**
+        @brief Sends output to the internal output buffer.
+    */
     void Shell::addOutput(const std::string& text, LineType type)
     {
@@ -199 +224 @@
     }
 
+    /**
+        @brief Clears the list of output-lines.
+    */
     void Shell::clearOutput()
     {
@@ -210 +238 @@
     }
 
+    /**
+        @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 +249 @@
     }
 
+    /**
+        @brief Returns the end() iterator of the list of output-lines.
+    */
     Shell::LineList::const_iterator Shell::getEndIterator() const
     {
@@ -223 +257 @@
     }
 
+    /**
+        @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 +274 @@
     }
 
+    /**
+        @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 +286 @@
     }
 
+    /**
+        @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 +294 @@
         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 +330 @@
             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 +352 @@
     }
 
-    void Shell::setPromptPrefix(const std::string& str)
-    {
-    }
-
 
     // ##########################################
@@ -307 +357 @@
     // ##########################################
 
+    /// InputBuffer callback: Called if the input changes.
     void Shell::inputChanged()
     {
@@ -313 +364 @@
     }
 
+    /// InputBuffer callback: Called if a key was pressed that executes a command (usually [return]).
     void Shell::execute()
     {
@@ -340 +392 @@
     }
 
+    /// InputBuffer callback: Called if a key was pressed that shows hints and completes a command (usually [tab]).
     void Shell::hintAndComplete()
     {
@@ -349 +402 @@
     }
 
+    /// InputBuffer callback: Called if a key was pressed that deletes the character before the cursor (usually [backspace]).
     void Shell::backspace()
     {
@@ -356 +410 @@
     }
 
-    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 +417 @@
     }
 
+    /// InputBuffer callback: Called if a key was pressed that moves the input cursor the right (usually [arrow right]).
     void Shell::cursorRight()
     {
@@ -383 +424 @@
     }
 
+    /// InputBuffer callback: Called if a key was pressed that moves the input cursor the left (usually [arrow left]).
     void Shell::cursorLeft()
     {
@@ -389 +431 @@
     }
 
+    /// 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 +438 @@
     }
 
+    /// 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 +445 @@
     }
 
+    /// InputBuffer callback: Called if a key was pressed that scrolls upwards through the history of entered commands (usually [arrow up]).
     void Shell::historyUp()
     {
@@ -410 +455 @@
     }
 
+    /// InputBuffer callback: Called if a key was pressed that scrolls downwards through the history of entered commands (usually [arrow down]).
     void Shell::historyDown()
     {
@@ -419 +465 @@
     }
 
+    /// 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 +484 @@
     }
 
+    /// 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 +503 @@
     }
 
+    /// 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 +515 @@
     }
 
+    /// 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 +526 @@
         }
     }
+
+    /// 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>();
+    }
 }

code/branches/doc/src/libraries/core/command/Shell.h

@@ -27 +27 @@
  */
 
+/**
+    @defgroup ShellConsole Shell and console
+    @ingroup Command
+*/
+
+/**
+    @file
+    @ingroup Command ShellConsole
+    @brief Declaration of the Shell and ShellListener classes.
+*/
+
 #ifndef _Shell_H__
 #define _Shell_H__
@@ -43 +54 @@
 namespace orxonox
 {
+    /**
+        @brief An interface, used to get a notification if the state of the Shell changes.
+    */
     class _CoreExport ShellListener
     {
@@ -51 +65 @@
 
         private:
-            virtual void linesChanged() {}
-            virtual void onlyLastLineChanged() {}
-            virtual void lineAdded() {}
-            virtual void inputChanged() {}
-            virtual void cursorChanged() {}
-            virtual void executed() {}
-            virtual void exit() {}
+            virtual void linesChanged() {}          ///< Called if all output-lines have changed
+            virtual void onlyLastLineChanged() {}   ///< Called if only the last output-line has changed
+            virtual void lineAdded() {}             ///< Called if a new line was added to the output
+            virtual void inputChanged() {}          ///< Called if the input has changed
+            virtual void cursorChanged() {}         ///< Called if the cursor in the input line has changed
+            virtual void executed() {}              ///< Called if a command from the input line was executed
+            virtual void exit() {}                  ///< Called if the console should be closed
     };
 
 
+    /**
+        @brief The Shell is the logical component of the console that displays output to the user and allows him to enter commands.
+
+        The Shell gathers output sent from OutputHandler by inheriting from OutputListener.
+        The output-lines are stored in the shell, so they can be displayed in a graphical
+        console. Additionally the Shell has an InputBuffer which is needed by the user to
+        enter commands.
+
+        Different graphical consoles build upon a Shell, for example InGameConsole and IOConsole.
+    */
     class _CoreExport Shell : virtual public OrxonoxClass, public OutputListener
     {
         public:
+            /// Defines the type of a line of text in the Shell - some types depend on the output level, others are of internal use.
             enum LineType
             {
@@ -88 +113 @@
             void unregisterListener(ShellListener* listener);
 
+            /// Returns the input buffer which is needed by the user to enter text into the shell.
             inline InputBuffer* getInputBuffer()
                 { return this->inputBuffer_; }
 
             void setCursorPosition(unsigned int cursor);
+            /// Returns the current position of the cursor in the input buffer.
             inline unsigned int getCursorPosition() const
                 { return this->inputBuffer_->getCursorPosition(); }
 
+            /// Returns the current content of the input buffer (the text which was entered by the user)
             inline const std::string& getInput() const
                 { return this->inputBuffer_->get(); }
@@ -105 +133 @@
             void clearOutput();
 
+            /// Returns the number of output-lines that are displayed in the shell.
             inline unsigned int getNumLines() const
                 { return this->outputLines_.size(); }
+            /// Returns the line which is currently viewed if the user scrolls through the older output-lines in the shell.
             inline unsigned int getScrollPosition() const
                 { return this->scrollPosition_; }
 
-            inline const std::string& getPromptPrefix() const { return this->promptPrefix_; }
-            void setPromptPrefix(const std::string& str);
-
+            /// Returns the cache size that is actually used in CommandExecutor, but placed here for better readability of the config file.
             static inline unsigned int getCacheSize()
                 { return Shell::cacheSize_s; }
@@ -145 +173 @@
             void exit();
 
+            /// Iterates through all registered @ref ShellListener "shell listeners" and calls the function @a F.
             template <void (ShellListener::*F)()>
             void updateListeners()
@@ -152 +181 @@
             }
 
-            std::list<ShellListener*> listeners_;
-            InputBuffer*              inputBuffer_;
-            std::stringstream         outputBuffer_;
-            bool                      bFinishedLastLine_;
-            LineList                  outputLines_;
-            LineList::const_iterator  scrollIterator_;
-            unsigned int              scrollPosition_;
-            unsigned int              historyPosition_;
-
-            std::string               promptPrefix_;
-            const std::string         consoleName_;
-            const bool                bScrollable_;
+            std::list<ShellListener*> listeners_;           ///< The registered shell listeners
+            InputBuffer*              inputBuffer_;         ///< The input buffer that is needed by the user to enter text
+            std::stringstream         outputBuffer_;        ///< The output buffer that is used to retrieve lines of output from OutputListener
+            bool                      bFinishedLastLine_;   ///< Stores if the most recent output-line was terminated with a line-break or if more output is expected for this line
+            LineList                  outputLines_;         ///< A list of all output-lines that were displayed in the shell so far
+            LineList::const_iterator  scrollIterator_;      ///< An iterator to an entry of the list of output-lines, changes if the user scrolls through the output in the shell
+            unsigned int              scrollPosition_;      ///< The number of the line that is currently being referenced by scrollIterator_
+            unsigned int              historyPosition_;     ///< If the user scrolls through the history of entered commands (stored in commandHistory_), this contains the currently viewed history entry
+
+            const std::string         consoleName_;         ///< The name of this shell - used to define the name of the soft-debug-level config-value
+            const bool                bScrollable_;         ///< If true, the user can scroll through the output-lines
 
             // Config values
-            unsigned int              maxHistoryLength_;
-            unsigned int              historyOffset_;
-            std::vector<std::string>  commandHistory_;
-            int                       softDebugLevel_;
-            static unsigned int       cacheSize_s;
+            unsigned int              maxHistoryLength_;    ///< The maximum number of saved commands
+            unsigned int              historyOffset_;       ///< The command history is a circular buffer, this variable defines the current write-offset
+            std::vector<std::string>  commandHistory_;      ///< The history of commands that were entered by the user
+            int                       softDebugLevel_;      ///< The maximum level of output that is displayed in the shell (will be passed to OutputListener to filter output)
+            static unsigned int       cacheSize_s;          ///< The maximum cache size of the CommandExecutor - this is stored here for better readability of the config file and because CommandExecutor is no OrxonoxClass
     };
 }

code/branches/doc/src/libraries/core/command/TclBind.cc

@@ -49 +49 @@
     TclBind* TclBind::singletonPtr_s = 0;
 
+    /**
+        @brief Constructor: Initializes the Tcl-interpreter with a given data path.
+        @param datapath Path to the directory that contains the Orxonox-specific Tcl-files
+    */
     TclBind::TclBind(const std::string& datapath)
     {
@@ -56 +60 @@
     }
 
+    /**
+        @brief Destructor: Deletes the Tcl-interpreter.
+    */
     TclBind::~TclBind()
     {
@@ -62 +69 @@
     }
 
+    /**
+        @brief Defines the path to the directory that contains the Orxonox-specific Tcl-files and initializes the Tcl-interpreter accordingly.
+    */
     void TclBind::setDataPath(const std::string& datapath)
     {
@@ -71 +81 @@
     }
 
+    /**
+        @brief Creates and initializes the Tcl-interpreter by registering all callbacks and defining some useful functions.
+    */
     void TclBind::initializeTclInterpreter()
     {
@@ -96 +109 @@
     }
 
+    /**
+        @brief Creates and initializes a new Tcl-interpreter and calls the Orxonox-specific
+        init.tcl script that defines some special functions which are required by Orxonox.
+    */
     Tcl::interpreter* TclBind::createTclInterpreter()
     {
@@ -116 +133 @@
     }
 
+    /**
+        @brief Returns the path to the Tcl-library (not the Orxonox-specific Tcl-files).
+    */
     std::string TclBind::getTclLibraryPath()
     {
@@ -128 +148 @@
     }
 
+    /**
+        @brief Callback: Used to send an Orxonox-command from Tcl to the CommandExecutor and to send its result back to Tcl.
+    */
     std::string TclBind::tcl_query(Tcl::object const &args)
     {
@@ -151 +174 @@
     }
 
+    /**
+        @brief Callback: Used to send an Orxonox-command from Tcl to the CommandExecutor.
+    */
     void TclBind::tcl_execute(Tcl::object const &args)
     {
@@ -162 +188 @@
     }
 
+    /**
+        @brief Console command, executes Tcl code. Can be used to bind Tcl-commands to a key, because native
+        Tcl-commands can not be evaluated and are thus not supported by the key-binder.
+    */
     std::string TclBind::tcl(const std::string& tclcode)
     {
@@ -182 +212 @@
     }
 
+    /**
+        @brief Console command and implementation of the Tcl-feature "bgerror" which is called if an error
+        occurred in the background of a Tcl-script.
+    */
     void TclBind::bgerror(const std::string& error)
     {
@@ -187 +221 @@
     }
 
+    /**
+        @brief Executes Tcl-code and returns the return-value.
+        @param tclcode A string that contains Tcl-code
+        @param error A pointer to an integer (or NULL) that is used to write an error-code (see @ref CommandExecutorErrorCodes "CommandExecutor error codes")
+        @return Returns the return-value of the executed code (or an empty string if there's no return-value)
+    */
     std::string TclBind::eval(const std::string& tclcode, int* error)
     {
@@ -194 +234 @@
         try
         {
+            // execute the code
             return TclBind::getInstance().interpreter_->eval(tclcode);
         }

code/branches/doc/src/libraries/core/command/TclBind.h

@@ -27 +27 @@
  */
 
+/**
+    @defgroup Tcl Tcl
+    @ingroup Command
+*/
+
+/**
+    @file
+    @ingroup Command Tcl
+    @brief Declaration of the TclBind class.
+
+    @anchor TclBindExample
+
+    orxonox::TclBind is a wrapper class for a Tcl interpreter. It is implemented as
+    singleton, so it can be accessed by everyone, but all share the same static
+    Tcl interpreter. If you need a Tcl interpreter at your own, see orxonox::TclThreadManager
+    for more information.
+
+    orxonox::TclBind is used by orxonox::CommandExecutor to execute Tcl commands. It can
+    also be used to execute Tcl commands from different sources, but note that they may
+    interfer with the ingame console if used improperly. By no means execute blocking
+    commands such as endless loops or the tcl command @c vwait. Use orxonox::TclThreadManager
+    and execute these commands in a multithreaded Tcl interpreter instead.
+
+    TclBind also defines different callback functions to return commands from the
+    Tcl interpreter back to Orxonox. Because of that it's possible to send a mixture
+    of Orxonox- and Tcl-commands to TclBind::eval() and still get the desired behavior.
+
+    Example:
+    @code
+    TclBind::eval("puts \"Hello World\"");                              // calls the tcl command "puts", prints "Hello World" to the console
+    TclBind::eval("log Hello World");                                   // calls the orxonox command "log", prints "Hello World" to the console
+
+    TclBind::eval("log [expr 1+1]");                                    // prints "2" to the console (which is the result of the tcl command "expr")
+
+    TclBind::eval("puts -nonewline Hello; log World");                  // prints "HelloWorld" to the console
+
+    TclBind::eval("for {set i 0} {$i < 10} {incr i} {log test: $i}");   // prints "test: 0", ..., "test: 9" to the console
+    @endcode
+
+    Note that @c puts and @c log behave slightly different, even though both can print
+    text to the console. @c puts needs quotation marks around multi-word output, while
+    @c log doesn't. @c puts on the other hand supports the flag @c -nonewline.
+
+    TclBind::eval() can also be used to obtain the return-value of a Tcl command:
+    @code
+    std::string result = TclBind::eval("expr 1+1");                     // result == "2"
+    @endcode
+*/
+
 #ifndef _TclBind_H__
 #define _TclBind_H__
@@ -38 +87 @@
 namespace orxonox
 {
+    /**
+        @brief A wrapper class for a Tcl interpreter. Used to execute Tcl commands.
+
+        TclBind is used to execute Tcl commands, for example if sent to CommandExecutor::execute().
+        It also defines different callbacks for Tcl, which allows to combine Orxonox-console-commands
+        and Tcl-function without problems.
+
+        @see See @ref TclBindExample "TclBind.h" for more information and an example.
+    */
     class _CoreExport TclBind : public Singleton<TclBind>
     {
@@ -49 +107 @@
 
             void setDataPath(const std::string& datapath);
-            const std::string& getTclDataPath() const { return this->tclDataPath_; }
             static std::string getTclLibraryPath();
+            /// Returns the path to the Orxonox-specific Tcl-files.
+            inline const std::string& getTclDataPath() const
+                { return this->tclDataPath_; }
 
             void initializeTclInterpreter();
             static Tcl::interpreter* createTclInterpreter();
-            Tcl::interpreter* getTclInterpreter() const { return this->interpreter_; }
+            /// Returns the Tcl-interpreter
+            inline Tcl::interpreter* getTclInterpreter() const
+                { return this->interpreter_; }
 
             static std::string tcl_query(Tcl::object const &args);
@@ -62 +124 @@
 
         private:
-            TclBind(const TclBind& other);
+            TclBind(const TclBind& other);      ///< Copy-constructor, not implemented
 
-            Tcl::interpreter* interpreter_;
-            std::string tclDataPath_;
-            bool bSetTclDataPath_;
+            Tcl::interpreter* interpreter_;     ///< The wrapped Tcl interpreter
+            std::string tclDataPath_;           ///< The path to the directory that contains the Orxonox-specific Tcl-files
+            bool bSetTclDataPath_;              ///< True if tclDataPath_ was defined (after a call to setDataPath())
 
-            static TclBind* singletonPtr_s;
+            static TclBind* singletonPtr_s;     ///< The singleton pointer
     };
 }

code/branches/doc/src/libraries/core/command/TclThreadList.h

@@ -27 +27 @@
  */
 
+/**
+    @file
+    @ingroup Command Tcl
+    @brief Definition of TclThreadList.
+*/
+
 #ifndef _TclThreadList_H__
 #define _TclThreadList_H__
@@ -40 +46 @@
 namespace orxonox
 {
+    /**
+        @brief A thread-safe implementation of a message queue, used by TclThreadManager.
+    */
     template <class T>
     class TclThreadList

code/branches/doc/src/libraries/core/command/TclThreadManager.cc

@@ -26 +26 @@
  *
  */
+
+/**
+    @file
+    @brief Implementation of TclThreadManager.
+*/
 
 #include "TclThreadManager.h"
@@ -387 +392 @@
         @param target_id The id of the target thread
         @param command The command to send as a query
-        @param bUseCommandExecutor Only used if the target_id is 0 (which references the main interpreter). In this case it means if the command should be passed to the CommandExecutor (true) or to the main Tcl interpreter (false). This is true when called by tcl_query and false when called by tcl_crossquery.
+        @param bUseCommandExecutor Only used if the target_id is 0 (which references the main interpreter). In this case it means if the command should be passed to the CommandExecutor (true) or to the main Tcl interpreter (false). This is true when called by tcl_query() and false when called by tcl_crossquery().
     */
     std::string TclThreadManager::_query(unsigned int source_id, unsigned int target_id, const std::string& command, bool bUseCommandExecutor)

code/branches/doc/src/libraries/core/command/TclThreadManager.h

@@ -26 +26 @@
  *
  */
+
+/**
+    @file
+    @ingroup Command Tcl
+    @brief Declaration of TclThreadManager, used to create multithreaded Tcl interpreters.
+*/
 
 #ifndef _TclThreadManager_H__