Changeset 7401 for code/trunk/src/libraries/core/command/ArgumentCompletionFunctions.cc

Timestamp:

Sep 11, 2010, 12:34:00 AM (14 years ago)

Author:

landauf

Message:

merged doc branch back to trunk

Location:

code/trunk

Files:

• . (modified) (1 prop)
• src/libraries/core/command/ArgumentCompletionFunctions.cc (modified) (18 diffs)

code/trunk/src/libraries/core/command/ArgumentCompletionFunctions.cc

@@ -26 +26 @@
  *
  */
+
+/**
+    @file
+    @brief Implementation of all argument completion functions
+*/
 
 #include "ArgumentCompletionFunctions.h"
@@ -53 +58 @@
     namespace autocompletion
     {
+        /**
+            @brief Fallback implementation, returns an empty list.
+        */
         ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(fallback)()
         {
@@ -60 +68 @@
         namespace detail
         {
+            /**
+                @brief Returns true if a group of console commands is visible (i.e. if at least one command in this group is visible).
+            */
             bool groupIsVisible(const std::map<std::string, ConsoleCommand*>& group, bool bOnlyShowHidden)
             {
@@ -69 +80 @@
             }
 
+            /**
+                @brief Returns a list of all console command groups AND all console command shortcuts.
+                @param fragment The last argument
+                @param bOnlyShowHidden If true, only hidden groups and commands are returned
+            */
             ArgumentCompletionList _groupsandcommands(const std::string& fragment, bool bOnlyShowHidden)
             {
+                // note: this function returns only arguments that begin with "fragment", which would't be necessary for the
+                //       auto-completion, but it's necessary to place the line-break "\n" between groups and commands
+                //       only if both groups AND commands are in the list.
+
                 ArgumentCompletionList groupList;
                 std::string fragmentLC = getLowercase(fragment);
 
+                // get all the groups that are visible (except the shortcut group "")
                 const std::map<std::string, std::map<std::string, ConsoleCommand*> >& commands = ConsoleCommand::getCommands();
                 for (std::map<std::string, std::map<std::string, ConsoleCommand*> >::const_iterator it_group = commands.begin(); it_group != commands.end(); ++it_group)
@@ -79 +100 @@
                         groupList.push_back(ArgumentCompletionListElement(it_group->first, getLowercase(it_group->first)));
 
+                // now add all shortcuts (in group "")
                 std::map<std::string, std::map<std::string, ConsoleCommand*> >::const_iterator it_group = commands.find("");
                 if (it_group != commands.end())
                 {
+                    // add a line-break if the list isn't empty
                     if (!groupList.empty())
                         groupList.push_back(ArgumentCompletionListElement("", "", "\n"));
 
+                    // add the shortcuts
                     for (std::map<std::string, ConsoleCommand*>::const_iterator it_command = it_group->second.begin(); it_command != it_group->second.end(); ++it_command)
                         if (it_command->second->isActive() && it_command->second->hasAccess() && (!it_command->second->isHidden())^bOnlyShowHidden && (fragmentLC == "" || getLowercase(it_command->first).find_first_of(fragmentLC) == 0))
@@ -90 +114 @@
                 }
 
+                // if no shortcut was added, remove the line-break again
                 if (!groupList.empty() && groupList.back().getDisplay() == "\n")
                     groupList.pop_back();
@@ -96 +121 @@
             }
 
+            /**
+                @brief Returns a list of all console commands in a given group.
+                @param fragment The last argument
+                @param group The group's name
+                @param bOnlyShowHidden If true, only hidden console commands are returned
+            */
             ArgumentCompletionList _subcommands(const std::string& fragment, const std::string& group, bool bOnlyShowHidden)
             {
@@ -102 +133 @@
                 std::string groupLC = getLowercase(group);
 
+                // find the iterator of the given group
                 std::map<std::string, std::map<std::string, ConsoleCommand*> >::const_iterator it_group = ConsoleCommand::getCommands().begin();
                 for ( ; it_group != ConsoleCommand::getCommands().end(); ++it_group)
@@ -107 +139 @@
                         break;
 
+                // add all commands in the group to the list
                 if (it_group != ConsoleCommand::getCommands().end())
                 {
@@ -118 +151 @@
         }
 
+        /**
+            @brief Returns a list of all console command groups AND all console command shortcuts.
+        */
         ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(groupsandcommands)(const std::string& fragment)
         {
@@ -123 +159 @@
         }
 
+        /**
+            @brief Returns a list of all console commands in a given group.
+        */
         ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(subcommands)(const std::string& fragment, const std::string& group)
         {
@@ -128 +167 @@
         }
 
+        /**
+            @brief Returns a list of commands and groups and also supports auto-completion of the arguments of these commands.
+
+            This is a multi-word function, because commands are composed of 1-2 words and additional arguments.
+        */
         ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_MULTI(command)(const std::string& fragment)
         {
@@ -145 +189 @@
         }
 
+        /**
+            @brief Returns a list of hidden commands and groups and also supports auto-completion of the arguments of these commands.
+
+            This is a multi-word function, because commands are composed of 1-2 words and additional arguments.
+
+            This function makes commands visible that would usually be hidden.
+        */
         ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_MULTI(hiddencommand)(const std::string& fragment)
         {
@@ -170 +221 @@
         }
 
+        /**
+            @brief Returns possible files and directories and also supports files in arbitrary deeply nested subdirectories.
+
+            This function returns files and directories in the given path. This allows to
+            navigate iteratively through the file system. The first argument @a fragment
+            is used to get the current path.
+        */
         ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(files)(const std::string& fragment)
         {
@@ -211 +269 @@
         }
 
+        /**
+            @brief Returns the sections of the config file.
+        */
         ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(settingssections)()
         {
@@ -222 +283 @@
         }
 
+        /**
+            @brief Returns the entries in a given section of the config file.
+        */
         ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(settingsentries)(const std::string& fragment, const std::string& section)
         {
@@ -235 +299 @@
         }
 
+        /**
+            @brief Returns the current value of a given value in a given section of the config file.
+        */
         ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(settingsvalue)(const std::string& fragment, const std::string& entry, const std::string& section)
         {
@@ -255 +322 @@
         }
 
+        /**
+            @brief Returns a list of indexes of the available Tcl threads (see TclThreadManager).
+        */
         ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(tclthreads)()
         {