Changeset 7361 for code/branches/doc/src/libraries/core/command/TclBind.h

Timestamp:

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

Author:

landauf

Message:

added documentation

File:

• code/branches/doc/src/libraries/core/command/TclBind.h (modified) (4 diffs)

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
     };
 }