Changeset 7352 for code/branches/doc/src/libraries/core/command/CommandEvaluation.h

Timestamp:

Sep 4, 2010, 11:33:02 PM (14 years ago)

Author:

landauf

Message:

added documentation

also some small naming and readability changes in the code.

File:

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

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

@@ -27 +27 @@
  */
 
+/**
+    @defgroup CommandExecEval Command execution and evaluation
+    @ingroup Command
+*/
+
+/**
+    @file
+    @ingroup Command CommandExecEval
+    @brief Declaration of the orxonox::CommandEvaluation class which is returned by orxonox::CommandExecutor::evaluate().
+
+    The orxonox::CommandEvaluation class gathers all information about a command-string. It is used
+    internally by orxonox::CommandExecutor and can also be returned by it to provide more information
+    about a command. It's also possible to evaluate the arguments of a command to execute it faster.
+
+    @see See @ref CommandExecutorExample "this description" for an example.
+*/
+
 #ifndef _CommandEvaluation_H__
 #define _CommandEvaluation_H__
@@ -41 +58 @@
 namespace orxonox
 {
+    /**
+        @brief CommandEvaluation is used to gather information about a command and to evaluate its arguments
+
+        This class provides several information about a command-string, for example the
+        evaluated ConsoleCommand, but also other information like hints if the command
+        is not yet finished.
+
+        @note You don't have to call evaluateArguments() manually, it's also done automatically
+        if you call the command the first time. However you can of course do it at any earlier
+        time, for example to return an error message if it doesn't work.
+
+        @remarks execCommand_ and hintCommand_ can be different in this case: There are multiple
+        commands avaliable, let's say "tcl", "tclexecute", and "tclquery". The user enters
+        "tcl", which is already a valid command. Now execCommand_ points to the "tcl"-command,
+        but hintCommand_ still points to the autocompletion command of CommandExecutor, because
+        the auto-completion list must still return the three possible commands, "tcl tclexecute tclquery"
+        because the user may want to execute "tclquery" and needs auto-completion.
+
+        @see See @ref CommandExecutorExample "this description" for an example.
+    */
     class _CoreExport CommandEvaluation
     {
@@ -56 +93 @@
             std::string getCommandSuggestion() const;
 
-            int evaluateParams(bool bPrintError = false);
+            int evaluateArguments(bool bPrintError = false);
 
+            /// Returns true if the command evaluation contains a valid command that can be executed.
             inline bool isValid() const
                 { return (this->execCommand_ != 0); }
 
+            /// Returns the console command that was evaluated by this object.
             inline const ConsoleCommand* getConsoleCommand() const
                 { return this->execCommand_; }
 
-            void setEvaluatedParameter(unsigned int index, const MultiType& param);
-            MultiType getEvaluatedParameter(unsigned int index) const;
+            void setEvaluatedArgument(unsigned int index, const MultiType& arg);
+            MultiType getEvaluatedArgument(unsigned int index) const;
 
+            /**
+                @brief Returns a list of possible arguments for the given command.
+
+                Note that the command's arguments may not be complete yet, so in this case
+                this list returns the possibilities. They can then be used to display a list
+                of the possible arguments or to apply auto-completion.
+            */
             const ArgumentCompletionList& getPossibleArguments() const
                 { return this->possibleArguments_; }
 
+            /// Returns the number of possible arguments. Empty ("") arguments are not counted.
             size_t getPossibleArgumentsSize() const
                 { return CommandEvaluation::getSize(this->possibleArguments_); }
@@ -90 +137 @@
             static std::string getCommonBegin(const ArgumentCompletionList& list);
 
-            const ConsoleCommand* execCommand_;
-            const ConsoleCommand* hintCommand_;
-            SubString tokens_;
-            std::string string_;
-            unsigned int execArgumentsOffset_;
-            unsigned int hintArgumentsOffset_;
-            bool bPossibleArgumentsRetrieved_;
-            ArgumentCompletionList possibleArguments_;
+            const ConsoleCommand* execCommand_;             ///< The command that will be executed (can be NULL if the command is not valid)
+            const ConsoleCommand* hintCommand_;             ///< The command that is used to display hints and argument lists (can be different to execCommand_ in some cases)
+            SubString tokens_;                              ///< The single words of the command string, split into tokens
+            std::string string_;                            ///< The original command string, entered by the user in the shell
+            unsigned int execArgumentsOffset_;              ///< The index of the first argument in tokens_ used to execute the command
+            unsigned int hintArgumentsOffset_;              ///< The index of the first argument in tokens_ used to display hints and argument lists
+            bool bPossibleArgumentsRetrieved_;              ///< True if the list of possible arguments was already retrieved
+            ArgumentCompletionList possibleArguments_;      ///< List of possible arguments for the command in the current state
 
-            bool bEvaluatedParams_;
-            bool bTriedToEvaluatedParams_;
-            unsigned int numberOfEvaluatedParams_;
-            MultiType param_[MAX_FUNCTOR_ARGUMENTS];
+            bool bEvaluatedArguments_;                      ///< True if the arguments of the command have been evaluated (and stored in arguments_)
+            bool bTriedToEvaluatedArguments_;               ///< True if an attempt was started to evaluate the arguments (but not necessarily successful)
+            unsigned int numberOfEvaluatedArguments_;       ///< The number of evaluated arguments (ranges from 0 to MAX_FUNCTOR_ARGUMENTS)
+            MultiType arguments_[MAX_FUNCTOR_ARGUMENTS];    ///< The evaluated arguments (the arguments from string_ or tokens_ converted to the right type)
     };
 }