<html><head><meta http-equiv="Content-Type" content="text/html charset=utf-8"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;">Hi Ari,<div>sorry for the delay in looking at this patch</div><div><br></div><div>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</div><div>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”</div><div><br></div><div>I can see a couple solutions here.</div><div>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”</div><div>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</div><div><br></div><div>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.</div><div><br></div><div>Let me know your thoughts</div><div><br></div><div><div>
<div style="color: rgb(0, 0, 0); letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;"><div style="color: rgb(0, 0, 0); letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;"><div style=" orphans: 2; widows: 2; border-collapse: separate; border-spacing: 0px;"><span style="font-size: 12px; orphans: auto; widows: auto;">Enrico Granata</span><br style="font-size: 12px; orphans: auto; widows: auto;"><span style="font-size: 12px; orphans: auto; widows: auto;">📩 egranata@</span><font color="#ff2600" style="font-size: 12px; orphans: auto; widows: auto;"></font><span style="font-size: 12px; orphans: auto; widows: auto;">.com</span><br style="font-size: 12px; orphans: auto; widows: auto;"><span style="font-size: 12px; orphans: auto; widows: auto;">☎️ 27683</span></div></div></div>
</div>
<br><div><div>On Dec 31, 2013, at 3:49 PM, Ari Grant <<a href="mailto:ari.grant@me.com">ari.grant@me.com</a>> wrote:</div><br class="Apple-interchange-newline"><blockquote type="cite">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.<br><br>This adds a help flag to specify a one line, brief help string for use in this case. Now a person can invoke:<br><br>(lldb) command script add -f somePyModule.somePyFunc -h "A quick hint about what this is."<br><br>and then calling 'help' will show the help string for the user added commands.<br><br><a href="http://llvm-reviews.chandlerc.com/D2495">http://llvm-reviews.chandlerc.com/D2495</a><br><br>Files:<br> include/lldb/lldb-enumerations.h<br> source/Commands/CommandObjectCommands.cpp<br> source/Interpreter/CommandObject.cpp<br><br>Index: include/lldb/lldb-enumerations.h<br>===================================================================<br>--- include/lldb/lldb-enumerations.h<br>+++ include/lldb/lldb-enumerations.h<br>@@ -394,6 +394,7 @@<br> eArgTypeFunctionName,<br> eArgTypeFunctionOrSymbol,<br> eArgTypeGDBFormat,<br>+ eArgTypeHelpString,<br> eArgTypeIndex,<br> eArgTypeLanguage,<br> eArgTypeLineNum,<br>Index: source/Commands/CommandObjectCommands.cpp<br>===================================================================<br>--- source/Commands/CommandObjectCommands.cpp<br>+++ source/Commands/CommandObjectCommands.cpp<br>@@ -1261,10 +1261,11 @@<br> CommandObjectPythonFunction (CommandInterpreter &interpreter,<br> std::string name,<br> std::string funct,<br>+ std::string help,<br> ScriptedCommandSynchronicity synch) :<br> CommandObjectRaw (interpreter,<br> name.c_str(),<br>- (std::string("Run Python function ") + funct).c_str(),<br>+ (help == "" ? (std::string("Run Python function ") + funct) : help).c_str(),<br> NULL),<br> m_function_name(funct),<br> m_synchro(synch),<br>@@ -1537,7 +1538,10 @@<br> m_options (interpreter)<br> {<br> CommandArgumentEntry arg1;<br>+ CommandArgumentEntry arg2;<br>+<br> CommandArgumentData cmd_arg;<br>+ CommandArgumentData help_arg;<br><br> // Define the first (and only) variant of this arg.<br> cmd_arg.arg_type = eArgTypeCommandName;<br>@@ -1545,9 +1549,17 @@<br><br> // There is only one variant this argument could be; put it into the argument entry.<br> arg1.push_back (cmd_arg);<br>- <br>- // Push the data for the first argument into the m_arguments vector.<br>+<br>+ // Define the first (and only) variant of this arg.<br>+ help_arg.arg_type = eArgTypeHelpString;<br>+ help_arg.arg_repetition = eArgRepeatPlain;<br>+<br>+ // There is only one variant this argument could be; put it into the argument entry.<br>+ arg2.push_back (help_arg);<br>+<br>+ // Push the data for the second argument into the m_arguments vector.<br> m_arguments.push_back (arg1);<br>+ m_arguments.push_back (arg2);<br> }<br><br> ~CommandObjectCommandsScriptAdd ()<br>@@ -1585,6 +1597,9 @@<br> case 'f':<br> m_funct_name = std::string(option_arg);<br> break;<br>+ case 'h':<br>+ m_help_string = std::string(option_arg);<br>+ break;<br> case 's':<br> m_synchronous = (ScriptedCommandSynchronicity) Args::StringToOptionEnum(option_arg, g_option_table[option_idx].enum_values, 0, error);<br> if (!error.Success())<br>@@ -1602,6 +1617,7 @@<br> OptionParsingStarting ()<br> {<br> m_funct_name = "";<br>+ m_help_string = "";<br> m_synchronous = eScriptedCommandSynchronicitySynchronous;<br> }<br><br>@@ -1618,6 +1634,7 @@<br> // Instance variables to hold the values for command options.<br><br> std::string m_funct_name;<br>+ std::string m_help_string;<br> ScriptedCommandSynchronicity m_synchronous;<br> };<br><br>@@ -1729,6 +1746,7 @@<br> CommandObjectSP command_obj_sp(new CommandObjectPythonFunction(m_interpreter,<br> m_cmd_name,<br> funct_name_str.c_str(),<br>+ "",<br> m_synchronous));<br><br> if (!m_interpreter.AddUserCommand(m_cmd_name, command_obj_sp, true))<br>@@ -1798,6 +1816,7 @@<br> CommandObjectSP new_cmd(new CommandObjectPythonFunction(m_interpreter,<br> cmd_name,<br> m_options.m_funct_name,<br>+ m_options.m_help_string,<br> m_options.m_synchronous));<br> if (m_interpreter.AddUserCommand(cmd_name, new_cmd, true))<br> {<br>@@ -1829,6 +1848,7 @@<br> CommandObjectCommandsScriptAdd::CommandOptions::g_option_table[] =<br> {<br> { LLDB_OPT_SET_1, false, "function", 'f', OptionParser::eRequiredArgument, NULL, 0, eArgTypePythonFunction, "Name of the Python function to bind to this command name."},<br>+ { LLDB_OPT_SET_1, false, "help", 'h', OptionParser::eRequiredArgument, NULL, 0, eArgTypeHelpString, "A string that briefly describes the command."},<br> { 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."},<br> { 0, false, NULL, 0, 0, NULL, 0, eArgTypeNone, NULL }<br> };<br>Index: source/Interpreter/CommandObject.cpp<br>===================================================================<br>--- source/Interpreter/CommandObject.cpp<br>+++ source/Interpreter/CommandObject.cpp<br>@@ -1110,6 +1110,7 @@<br> { eArgTypeFunctionName, "function-name", CommandCompletions::eNoCompletion, { NULL, false }, "The name of a function." },<br> { eArgTypeFunctionOrSymbol, "function-or-symbol", CommandCompletions::eNoCompletion, { NULL, false }, "The name of a function or symbol." },<br> { eArgTypeGDBFormat, "gdb-format", CommandCompletions::eNoCompletion, { GDBFormatHelpTextCallback, true }, NULL },<br>+ { eArgTypeHelpString, "help-string", CommandCompletions::eNoCompletion, { NULL, false }, "A brief help string summarizing a function or symbol." },<br> { eArgTypeIndex, "index", CommandCompletions::eNoCompletion, { NULL, false }, "An index into a list." },<br> { eArgTypeLanguage, "language", CommandCompletions::eNoCompletion, { LanguageTypeHelpTextCallback, true }, NULL },<br> { eArgTypeLineNum, "linenum", CommandCompletions::eNoCompletion, { NULL, false }, "Line number in a source file." },<br><span><D2495.1.patch></span>_______________________________________________<br>lldb-commits mailing list<br>lldb-commits@cs.uiuc.edu<br>http://lists.cs.uiuc.edu/mailman/listinfo/lldb-commits<br></blockquote></div><br></div></body></html>