Add a --help (-h) option to "command script add" that enables users to define a one-liner short help for their command

Also, in case they don't define any, change the default from "Run Python function <blah>" into "For more information run help <blah>"

The core issue here is that Python only allows one docstring per function, so we can't really attach both a short and a long help to the same command easily
There are alternatives but this is not a pressing enough concern to go through the motions quite yet

Fixes rdar://18322737

llvm-svn: 217795

4 files changed, 34 insertions, 13 deletions

diff --git a/lldb/include/lldb/lldb-enumerations.h b/lldb/include/lldb/lldb-enumerations.h
index 612487fd4fa..b95871cadb0 100644
--- a/lldb/include/lldb/lldb-enumerations.h
+++ b/lldb/include/lldb/lldb-enumerations.h
@@ -432,6 +432,7 @@ namespace lldb {
         eArgTypeFunctionName,
         eArgTypeFunctionOrSymbol,
         eArgTypeGDBFormat,
+        eArgTypeHelpText,
         eArgTypeIndex,
         eArgTypeLanguage,
         eArgTypeLineNum,
diff --git a/lldb/source/Commands/CommandObjectCommands.cpp b/lldb/source/Commands/CommandObjectCommands.cpp
index 7d9bb7dad8f..6061a1d7620 100644
--- a/lldb/source/Commands/CommandObjectCommands.cpp
+++ b/lldb/source/Commands/CommandObjectCommands.cpp
@@ -1292,15 +1292,24 @@ public:
     CommandObjectPythonFunction (CommandInterpreter &interpreter,
                                  std::string name,
                                  std::string funct,
+                                 std::string help,
                                  ScriptedCommandSynchronicity synch) :
         CommandObjectRaw (interpreter,
                           name.c_str(),
-                          (std::string("Run Python function ") + funct).c_str(),
+                          NULL,
                           NULL),
         m_function_name(funct),
         m_synchro(synch),
         m_fetched_help_long(false)
     {
+        if (!help.empty())
+            SetHelp(help.c_str());
+        else
+        {
+            StreamString stream;
+            stream.Printf("For more information run 'help %s'",name.c_str());
+            SetHelp(stream.GetData());
+        }
     }
     
     virtual
@@ -1617,7 +1626,12 @@ protected:
             switch (short_option)
             {
                 case 'f':
-                    m_funct_name = std::string(option_arg);
+                    if (option_arg)
+                        m_funct_name.assign(option_arg);
+                    break;
+                case 'h':
+                    if (option_arg)
+                        m_short_help.assign(option_arg);
                     break;
                 case 's':
                     m_synchronicity = (ScriptedCommandSynchronicity) Args::StringToOptionEnum(option_arg, g_option_table[option_idx].enum_values, 0, error);
@@ -1635,7 +1649,8 @@ protected:
         void
         OptionParsingStarting ()
         {
-            m_funct_name = "";
+            m_funct_name.clear();
+            m_short_help.clear();
             m_synchronicity = eScriptedCommandSynchronicitySynchronous;
         }
         
@@ -1652,6 +1667,7 @@ protected:
         // Instance variables to hold the values for command options.
         
         std::string m_funct_name;
+        std::string m_short_help;
         ScriptedCommandSynchronicity m_synchronicity;
     };
 
@@ -1695,6 +1711,7 @@ protected:
                         CommandObjectSP command_obj_sp(new CommandObjectPythonFunction (m_interpreter,
                                                                                         m_cmd_name,
                                                                                         funct_name_str.c_str(),
+                                                                                        m_short_help,
                                                                                         m_synchronicity));
                         
                         if (!m_interpreter.AddUserCommand(m_cmd_name, command_obj_sp, true))
@@ -1748,8 +1765,9 @@ protected:
             return false;
         }
         
-        // Store the command name and synchronicity in case we get multi-line input
+        // Store the options in case we get multi-line input
         m_cmd_name = command.GetArgumentAtIndex(0);
+        m_short_help.assign(m_options.m_short_help);
         m_synchronicity = m_options.m_synchronicity;
         
         if (m_options.m_funct_name.empty())
@@ -1764,6 +1782,7 @@ protected:
             CommandObjectSP new_cmd(new CommandObjectPythonFunction(m_interpreter,
                                                                     m_cmd_name,
                                                                     m_options.m_funct_name,
+                                                                    m_options.m_short_help,
                                                                     m_synchronicity));
             if (m_interpreter.AddUserCommand(m_cmd_name, new_cmd, true))
             {
@@ -1782,6 +1801,7 @@ protected:
     
     CommandOptions m_options;
     std::string m_cmd_name;
+    std::string m_short_help;
     ScriptedCommandSynchronicity m_synchronicity;
 };
 
@@ -1797,6 +1817,7 @@ OptionDefinition
 CommandObjectCommandsScriptAdd::CommandOptions::g_option_table[] =
 {
     { LLDB_OPT_SET_1, false, "function", 'f', OptionParser::eRequiredArgument, NULL, NULL, 0, eArgTypePythonFunction,        "Name of the Python function to bind to this command name."},
+    { LLDB_OPT_SET_1, false, "help"  , 'h', OptionParser::eRequiredArgument, NULL, NULL, 0, eArgTypeHelpText, "The help text to display for this command."},
     { LLDB_OPT_SET_1, false, "synchronicity", 's', OptionParser::eRequiredArgument, NULL, g_script_synchro_type, 0, eArgTypeScriptedCommandSynchronicity,        "Set the synchronicity of this command's executions with regard to LLDB event system."},
     { 0, false, NULL, 0, 0, NULL, NULL, 0, eArgTypeNone, NULL }
 };
diff --git a/lldb/source/Interpreter/CommandObject.cpp b/lldb/source/Interpreter/CommandObject.cpp
index 3fdbf994fe7..d8eade836ba 100644
--- a/lldb/source/Interpreter/CommandObject.cpp
+++ b/lldb/source/Interpreter/CommandObject.cpp
@@ -1103,6 +1103,7 @@ CommandObject::g_arguments_data[] =
     { eArgTypeFunctionName, "function-name", CommandCompletions::eNoCompletion, { nullptr, false }, "The name of a function." },
     { eArgTypeFunctionOrSymbol, "function-or-symbol", CommandCompletions::eNoCompletion, { nullptr, false }, "The name of a function or symbol." },
     { eArgTypeGDBFormat, "gdb-format", CommandCompletions::eNoCompletion, { GDBFormatHelpTextCallback, true }, nullptr },
+    { eArgTypeHelpText, "help-text", CommandCompletions::eNoCompletion, { nullptr, false }, "Text to be used as help for some other entity in LLDB" },
     { eArgTypeIndex, "index", CommandCompletions::eNoCompletion, { nullptr, false }, "An index into a list." },
     { eArgTypeLanguage, "language", CommandCompletions::eNoCompletion, { LanguageTypeHelpTextCallback, true }, nullptr },
     { eArgTypeLineNum, "linenum", CommandCompletions::eNoCompletion, { nullptr, false }, "Line number in a source file." },
diff --git a/lldb/test/functionalities/command_script/TestCommandScript.py b/lldb/test/functionalities/command_script/TestCommandScript.py
index 63f67b24d86..6efda1c46aa 100644
--- a/lldb/test/functionalities/command_script/TestCommandScript.py
+++ b/lldb/test/functionalities/command_script/TestCommandScript.py
@@ -59,16 +59,15 @@ class CmdPythonTestCase(TestBase):
                                'A command that says hello to LLDB users'])
 
         self.expect("help",
-                    substrs = ['Run Python function welcome.welcome_impl',
+                    substrs = ['For more information run',
                                'welcome'])
 
         self.expect("help -a",
-                    substrs = ['Run Python function welcome.welcome_impl',
+                    substrs = ['For more information run',
                                'welcome'])
 
         self.expect("help -u", matching=False,
-                    substrs = ['Run Python function welcome.welcome_impl',
-                               'welcome'])
+                    substrs = ['For more information run'])
 
         self.runCmd("command script delete welcome");
 
@@ -83,11 +82,10 @@ class CmdPythonTestCase(TestBase):
 
         self.expect('command script list',
             substrs = ['targetname',
-                       'Run Python function welcome.target_name_impl'])
+                       'For more information run'])
 
         self.expect("help targetname",
-                    substrs = ['Run Python function welcome.target_name_imp',
-                               'This command takes','\'raw\' input',
+                    substrs = ['This command takes','\'raw\' input',
                                'quote stuff'])
 
         self.expect("longwait",
@@ -112,8 +110,8 @@ class CmdPythonTestCase(TestBase):
                     substrs = ['I am running sync'])
 
         # Test that a python command can redefine itself
-        self.expect('command script add -f foobar welcome')
-
+        self.expect('command script add -f foobar welcome -h "just some help"')
+        
         self.runCmd("command script clear")
 
         # Test that re-defining an existing command works