Hi Ari, sorry for the delay in looking at this patch I have a gut feeling it would be best, if possible, to let the command itself provide a docstring, rather than rely on command-line artifacts for such purposes While in practice, I expect most commands to be added through __lldb_init_module calls rather than manually, it still feels hacky to me to have a flag for “help string”
I can see a couple solutions here. One would be to, say, extract the first line of the __doc__ attribute and use that as the “short help”, keeping the full __doc__string for “long help” Or we could add a custom attribute, say __lldb_helpstring__ to the function object, and if available, fetch and use it as the short help I am not specifically wed to either approach, and definitely open to other alternatives, it just strikes me as unclean to have the command add operation also provide a short help string, instead of somehow keeping this as much as possible within the command itself. Let me know your thoughts Enrico Granata 📩 egranata@.com ☎️ 27683 On Dec 31, 2013, at 3:49 PM, Ari Grant <[email protected]> wrote: > Currently the help command in LLDB will print the __doc__ string for any > python commands a user has added. However, when help is called without any > arguments all commands are listed and the help shown for python commands is > unhelpful. The message is a vague description the includes no more than the > function name the command calls into. > > This adds a help flag to specify a one line, brief help string for use in > this case. Now a person can invoke: > > (lldb) command script add -f somePyModule.somePyFunc -h "A quick hint about > what this is." > > and then calling 'help' will show the help string for the user added commands. > > http://llvm-reviews.chandlerc.com/D2495 > > Files: > include/lldb/lldb-enumerations.h > source/Commands/CommandObjectCommands.cpp > source/Interpreter/CommandObject.cpp > > Index: include/lldb/lldb-enumerations.h > =================================================================== > --- include/lldb/lldb-enumerations.h > +++ include/lldb/lldb-enumerations.h > @@ -394,6 +394,7 @@ > eArgTypeFunctionName, > eArgTypeFunctionOrSymbol, > eArgTypeGDBFormat, > + eArgTypeHelpString, > eArgTypeIndex, > eArgTypeLanguage, > eArgTypeLineNum, > Index: source/Commands/CommandObjectCommands.cpp > =================================================================== > --- source/Commands/CommandObjectCommands.cpp > +++ source/Commands/CommandObjectCommands.cpp > @@ -1261,10 +1261,11 @@ > 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(), > + (help == "" ? (std::string("Run Python function ") > + funct) : help).c_str(), > NULL), > m_function_name(funct), > m_synchro(synch), > @@ -1537,7 +1538,10 @@ > m_options (interpreter) > { > CommandArgumentEntry arg1; > + CommandArgumentEntry arg2; > + > CommandArgumentData cmd_arg; > + CommandArgumentData help_arg; > > // Define the first (and only) variant of this arg. > cmd_arg.arg_type = eArgTypeCommandName; > @@ -1545,9 +1549,17 @@ > > // There is only one variant this argument could be; put it into the > argument entry. > arg1.push_back (cmd_arg); > - > - // Push the data for the first argument into the m_arguments vector. > + > + // Define the first (and only) variant of this arg. > + help_arg.arg_type = eArgTypeHelpString; > + help_arg.arg_repetition = eArgRepeatPlain; > + > + // There is only one variant this argument could be; put it into the > argument entry. > + arg2.push_back (help_arg); > + > + // Push the data for the second argument into the m_arguments vector. > m_arguments.push_back (arg1); > + m_arguments.push_back (arg2); > } > > ~CommandObjectCommandsScriptAdd () > @@ -1585,6 +1597,9 @@ > case 'f': > m_funct_name = std::string(option_arg); > break; > + case 'h': > + m_help_string = std::string(option_arg); > + break; > case 's': > m_synchronous = (ScriptedCommandSynchronicity) > Args::StringToOptionEnum(option_arg, g_option_table[option_idx].enum_values, > 0, error); > if (!error.Success()) > @@ -1602,6 +1617,7 @@ > OptionParsingStarting () > { > m_funct_name = ""; > + m_help_string = ""; > m_synchronous = eScriptedCommandSynchronicitySynchronous; > } > > @@ -1618,6 +1634,7 @@ > // Instance variables to hold the values for command options. > > std::string m_funct_name; > + std::string m_help_string; > ScriptedCommandSynchronicity m_synchronous; > }; > > @@ -1729,6 +1746,7 @@ > CommandObjectSP command_obj_sp(new > CommandObjectPythonFunction(m_interpreter, > > m_cmd_name, > > funct_name_str.c_str(), > + > "", > > m_synchronous)); > > if (!m_interpreter.AddUserCommand(m_cmd_name, command_obj_sp, > true)) > @@ -1798,6 +1816,7 @@ > CommandObjectSP new_cmd(new > CommandObjectPythonFunction(m_interpreter, > cmd_name, > > m_options.m_funct_name, > + > m_options.m_help_string, > > m_options.m_synchronous)); > if (m_interpreter.AddUserCommand(cmd_name, new_cmd, true)) > { > @@ -1829,6 +1848,7 @@ > CommandObjectCommandsScriptAdd::CommandOptions::g_option_table[] = > { > { LLDB_OPT_SET_1, false, "function", 'f', > OptionParser::eRequiredArgument, NULL, 0, eArgTypePythonFunction, > "Name of the Python function to bind to this command name."}, > + { LLDB_OPT_SET_1, false, "help", 'h', OptionParser::eRequiredArgument, > NULL, 0, eArgTypeHelpString, "A string that briefly describes the > command."}, > { LLDB_OPT_SET_1, false, "synchronicity", 's', > OptionParser::eRequiredArgument, 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, 0, eArgTypeNone, NULL } > }; > Index: source/Interpreter/CommandObject.cpp > =================================================================== > --- source/Interpreter/CommandObject.cpp > +++ source/Interpreter/CommandObject.cpp > @@ -1110,6 +1110,7 @@ > { eArgTypeFunctionName, "function-name", > CommandCompletions::eNoCompletion, { NULL, false }, "The name of a function." > }, > { eArgTypeFunctionOrSymbol, "function-or-symbol", > CommandCompletions::eNoCompletion, { NULL, false }, "The name of a function > or symbol." }, > { eArgTypeGDBFormat, "gdb-format", CommandCompletions::eNoCompletion, { > GDBFormatHelpTextCallback, true }, NULL }, > + { eArgTypeHelpString, "help-string", CommandCompletions::eNoCompletion, > { NULL, false }, "A brief help string summarizing a function or symbol." }, > { eArgTypeIndex, "index", CommandCompletions::eNoCompletion, { NULL, > false }, "An index into a list." }, > { eArgTypeLanguage, "language", CommandCompletions::eNoCompletion, { > LanguageTypeHelpTextCallback, true }, NULL }, > { eArgTypeLineNum, "linenum", CommandCompletions::eNoCompletion, { NULL, > false }, "Line number in a source file." }, > <D2495.1.patch>_______________________________________________ > lldb-commits mailing list > [email protected] > http://lists.cs.uiuc.edu/mailman/listinfo/lldb-commits
_______________________________________________ lldb-commits mailing list [email protected] http://lists.cs.uiuc.edu/mailman/listinfo/lldb-commits
