Add some documentation on how HandleCommand work.

llvm-svn: 175717

diff --git a/lldb/include/lldb/API/SBCommandInterpreter.h b/lldb/include/lldb/API/SBCommandInterpreter.h
index ebcb6bf..9b2583c 100644 (file)
--- a/lldb/include/lldb/API/SBCommandInterpreter.h
+++ b/lldb/include/lldb/API/SBCommandInterpreter.h
@@ -85,8 +85,18 @@ public:
     lldb::ReturnStatus
     HandleCommand (const char *command_line, lldb::SBCommandReturnObject &result, bool add_to_history = false);
 
-    // This interface is not useful in SWIG, since the cursor & last_char arguments are string pointers INTO current_line
-    // and you can't do that in a scripting language interface in general... 
+    // The pointer based interface is not useful in SWIG, since the cursor & last_char arguments are string pointers INTO current_line
+    // and you can't do that in a scripting language interface in general...
+    
+    // In either case, the way this works is that the you give it a line and cursor position in the line.  The function
+    // will return the number of completions.  The matches list will contain number_of_completions + 1 elements.  The first
+    // element is the common substring after the cursor position for all the matches.  The rest of the elements are the
+    // matches.  The first element is useful if you are emulating the common shell behavior where the tab completes
+    // to the string that is common among all the matches, then you should first check if the first element is non-empty,
+    // and if so just insert it and move the cursor to the end of the insertion.  The next tab will return an empty
+    // common substring, and a list of choices (if any), at which point you should display the choices and let the user
+    // type further to disambiguate.
+    
     int
     HandleCompletion (const char *current_line,
                       const char *cursor,