When defining a scripted command, it is possible to provide a docstring and that will be used as the help text for the command

 If no docstring is provided, a default help text is created
LLDB will refuse to create scripted commands if the scripting language is anything but Python
Some additional comments in AppleObjCRuntimeV2.cpp to describe the memory layout expected by the dynamic type lookup code

llvm-svn: 137801

9 files changed, 107 insertions, 8 deletions

diff --git a/lldb/include/lldb/Interpreter/CommandObject.h b/lldb/include/lldb/Interpreter/CommandObject.h
index 525fc454eef..f389ab875da 100644
--- a/lldb/include/lldb/Interpreter/CommandObject.h
+++ b/lldb/include/lldb/Interpreter/CommandObject.h
@@ -112,6 +112,9 @@ public:
     SetHelpLong (const char * str);
 
     void
+    SetHelpLong (std::string str);
+
+    void
     SetSyntax (const char *str);
 
     virtual void
diff --git a/lldb/include/lldb/Interpreter/ScriptInterpreter.h b/lldb/include/lldb/Interpreter/ScriptInterpreter.h
index a2e620d6f61..4d494f732c9 100644
--- a/lldb/include/lldb/Interpreter/ScriptInterpreter.h
+++ b/lldb/include/lldb/Interpreter/ScriptInterpreter.h
@@ -191,6 +191,12 @@ public:
     {
         return false;
     }
+    
+    virtual std::string
+    GetDocumentationForItem(const char* item)
+    {
+        return std::string("");
+    }
 
     const char *
     GetScriptInterpreterPtyName ();
diff --git a/lldb/include/lldb/Interpreter/ScriptInterpreterPython.h b/lldb/include/lldb/Interpreter/ScriptInterpreterPython.h
index feb65eb98be..8e5033b3c41 100644
--- a/lldb/include/lldb/Interpreter/ScriptInterpreterPython.h
+++ b/lldb/include/lldb/Interpreter/ScriptInterpreterPython.h
@@ -109,6 +109,9 @@ public:
     static std::string
     CallPythonScriptFunction (const char *python_function_name,
                               lldb::ValueObjectSP valobj);
+    
+    virtual std::string
+    GetDocumentationForItem(const char* item);
 
     void
     CollectDataForBreakpointCommandCallback (BreakpointOptions *bp_options,
diff --git a/lldb/source/Commands/CommandObjectCommands.cpp b/lldb/source/Commands/CommandObjectCommands.cpp
index 6c12126d4f5..d722d1d17e1 100644
--- a/lldb/source/Commands/CommandObjectCommands.cpp
+++ b/lldb/source/Commands/CommandObjectCommands.cpp
@@ -24,6 +24,8 @@
 #include "lldb/Interpreter/CommandObjectRegexCommand.h"
 #include "lldb/Interpreter/CommandReturnObject.h"
 #include "lldb/Interpreter/Options.h"
+#include "lldb/Interpreter/ScriptInterpreter.h"
+#include "lldb/Interpreter/ScriptInterpreterPython.h"
 
 using namespace lldb;
 using namespace lldb_private;
@@ -1155,6 +1157,13 @@ public:
                    NULL),
     m_function_name(funct)
     {
+        ScriptInterpreter* scripter = m_interpreter.GetScriptInterpreter();
+        if (scripter)
+        {
+            std::string docstring = scripter->GetDocumentationForItem(funct.c_str());
+            if (!docstring.empty())
+                SetHelpLong(docstring);
+        }
     }
     
     virtual
@@ -1427,6 +1436,14 @@ public:
      CommandReturnObject &result
      )
     {
+        
+        if (m_interpreter.GetDebugger().GetScriptLanguage() != lldb::eScriptLanguagePython)
+        {
+            result.AppendError ("only scripting language supported for scripted commands is currently Python");
+            result.SetStatus (eReturnStatusFailed);
+            return false;
+        }
+        
         size_t argc = args.GetArgumentCount();
         
         if (argc != 1)
diff --git a/lldb/source/Interpreter/CommandObject.cpp b/lldb/source/Interpreter/CommandObject.cpp
index 635d9a58838..1607d8e11c2 100644
--- a/lldb/source/Interpreter/CommandObject.cpp
+++ b/lldb/source/Interpreter/CommandObject.cpp
@@ -129,6 +129,12 @@ CommandObject::SetHelpLong (const char *cstr)
 }
 
 void
+CommandObject::SetHelpLong (std::string str)
+{
+    m_cmd_help_long = str;
+}
+
+void
 CommandObject::SetSyntax (const char *cstr)
 {
     m_cmd_syntax = cstr;
diff --git a/lldb/source/Interpreter/ScriptInterpreterPython.cpp b/lldb/source/Interpreter/ScriptInterpreterPython.cpp
index 4db56d4ac23..e84cd699549 100644
--- a/lldb/source/Interpreter/ScriptInterpreterPython.cpp
+++ b/lldb/source/Interpreter/ScriptInterpreterPython.cpp
@@ -763,13 +763,13 @@ ScriptInterpreterPython::ExecuteOneLineWithReturn (const char *in_string,
                 case eCharPtr: // "char *"
                 {
                     const char format[3] = "s#";
-                    success = PyArg_Parse (py_return, format, (char **) &ret_value);
+                    success = PyArg_Parse (py_return, format, (char **) ret_value);
                     break;
                 }
                 case eCharStrOrNone: // char* or NULL if py_return == Py_None
                 {
                     const char format[3] = "z";
-                    success = PyArg_Parse (py_return, format, (char **) &ret_value);
+                    success = PyArg_Parse (py_return, format, (char **) ret_value);
                     break;
                 }
                 case eBool:
@@ -1972,6 +1972,26 @@ ScriptInterpreterPython::RunScriptBasedCommand(const char* impl_function,
     
 }
 
+// in Python, a special attribute __doc__ contains the docstring
+// for an object (function, method, class, ...) if any is defined
+// Otherwise, the attribute's value is None
+std::string
+ScriptInterpreterPython::GetDocumentationForItem(const char* item)
+{
+    std::string command(item);
+    command += ".__doc__";
+    
+    char* result_ptr = NULL; // Python is going to point this to valid data if ExecuteOneLineWithReturn returns successfully
+    
+    if (ExecuteOneLineWithReturn (command.c_str(),
+                                 ScriptInterpreter::eCharStrOrNone,
+                                 &result_ptr) && result_ptr)
+    {
+        return std::string(result_ptr);
+    }
+    else
+        return std::string("");
+}
 
 void
 ScriptInterpreterPython::InitializeInterpreter (SWIGInitCallback python_swig_init_callback,
diff --git a/lldb/source/Plugins/LanguageRuntime/ObjC/AppleObjCRuntime/AppleObjCRuntimeV2.cpp b/lldb/source/Plugins/LanguageRuntime/ObjC/AppleObjCRuntime/AppleObjCRuntimeV2.cpp
index f80015f977b..75a0a6a085e 100644
--- a/lldb/source/Plugins/LanguageRuntime/ObjC/AppleObjCRuntime/AppleObjCRuntimeV2.cpp
+++ b/lldb/source/Plugins/LanguageRuntime/ObjC/AppleObjCRuntime/AppleObjCRuntimeV2.cpp
@@ -568,9 +568,9 @@ AppleObjCRuntimeV2::GetByteOffsetForIvar (ClangASTType &parent_ast_type, const c
 
 // tagged pointers are marked by having their least-significant bit
 // set. this makes them "invalid" as pointers because they violate
-// the alignment requirements. this way, we can always know when
-// we are dealing with a tagged pointer, and use the lookup approach
-// that the runtime would
+// the alignment requirements. of course, this detection algorithm
+// is not accurate (it might become better by incorporating further
+// knowledge about the internals of tagged pointers)
 bool
 AppleObjCRuntimeV2::IsTaggedPointer(lldb::addr_t ptr)
 {
@@ -578,6 +578,9 @@ AppleObjCRuntimeV2::IsTaggedPointer(lldb::addr_t ptr)
 }
 
 
+// this code relies on the assumption that an Objective-C object always starts
+// with an ISA at offset 0. an ISA is effectively a pointer to an instance of
+// struct class_t in the ObjCv2 runtime
 lldb_private::ObjCLanguageRuntime::ObjCISA
 AppleObjCRuntimeV2::GetISA(ValueObject& valobj)
 {
@@ -587,8 +590,8 @@ AppleObjCRuntimeV2::GetISA(ValueObject& valobj)
     {
         // when using the expression parser, an additional layer of "frozen data"
         // can be created, which is basically a byte-exact copy of the data returned
-        // by the expression, but in host memory. because Python code might need to read
-        // into the object memory in non-obvious ways, we need to hand it the target version
+        // by the expression, but in host memory. because this code reads memory without
+        // taking the debug-info-provided object layout, we need to hand it the target version
         // of the expression output
         lldb::addr_t tgt_address = valobj.GetValueAsUnsigned();
         ValueObjectSP target_object = ValueObjectConstResult::Create (valobj.GetExecutionContextScope(),
@@ -647,9 +650,20 @@ AppleObjCRuntimeV2::GetActualTypeName(lldb_private::ObjCLanguageRuntime::ObjCISA
     
     uint8_t pointer_size = m_process->GetAddressByteSize();
     Error error;
+    
+    /*
+     struct class_t *isa;
+     struct class_t *superclass;
+     Cache cache;
+     IMP *vtable;
+-->     uintptr_t data_NEVER_USE;
+     WARNING: this data_NEVER_USE pointer might one day contain flags in the least-significant bits
+     currently, rdar://problem/8955342 prevents the runtime from doing so
+     it presently is just a pointer to a class_rw_t
+     */
+    
     lldb::addr_t rw_pointer = isa + (4 * pointer_size);
     //printf("rw_pointer: %llx\n", rw_pointer);
-    
     uint64_t data_pointer =  m_process->ReadUnsignedIntegerFromMemory(rw_pointer,
                                                                       pointer_size,
                                                                       0,
@@ -657,6 +671,12 @@ AppleObjCRuntimeV2::GetActualTypeName(lldb_private::ObjCLanguageRuntime::ObjCISA
     if (error.Fail())
         return ConstString("unknown");
     
+    /*
+     uint32_t flags;
+     uint32_t version;
+     
+-->     const class_ro_t *ro;
+     */
     data_pointer += 8;
     //printf("data_pointer: %llx\n", data_pointer);
     uint64_t ro_pointer = m_process->ReadUnsignedIntegerFromMemory(data_pointer,
@@ -666,6 +686,18 @@ AppleObjCRuntimeV2::GetActualTypeName(lldb_private::ObjCLanguageRuntime::ObjCISA
     if (error.Fail())
         return ConstString("unknown");
     
+    /*
+     uint32_t flags;
+     uint32_t instanceStart;
+     uint32_t instanceSize;
+     #ifdef __LP64__
+     uint32_t reserved;
+     #endif
+     
+     const uint8_t * ivarLayout;
+     
+-->     const char * name;
+     */
     ro_pointer += 12;
     if (pointer_size == 8)
         ro_pointer += 4;
@@ -722,6 +754,10 @@ AppleObjCRuntimeV2::GetParentClass(lldb_private::ObjCLanguageRuntime::ObjCISA is
     
     uint8_t pointer_size = m_process->GetAddressByteSize();
     Error error;
+    /*
+     struct class_t *isa;
+-->     struct class_t *superclass;
+     */
     lldb::addr_t parent_pointer = isa + pointer_size;
     //printf("rw_pointer: %llx\n", rw_pointer);
     
diff --git a/lldb/test/functionalities/alias/TestAliases.py b/lldb/test/functionalities/alias/TestAliases.py
index 4f43136f24d..bfcafa38fac 100644
--- a/lldb/test/functionalities/alias/TestAliases.py
+++ b/lldb/test/functionalities/alias/TestAliases.py
@@ -134,6 +134,10 @@ class AliasTestCase(TestBase):
 
         self.expect('welcome Enrico',
             substrs = ['Hello Enrico, welcome to LLDB']);
+                
+        self.expect("help welcome",
+                    substrs = ['Just a docstring for welcome_impl',
+                               'A command that says hello to LLDB users'])
 
         self.runCmd("command script delete welcome");
 
diff --git a/lldb/test/functionalities/alias/welcome.py b/lldb/test/functionalities/alias/welcome.py
index db90e89ee4e..3b63c702327 100644
--- a/lldb/test/functionalities/alias/welcome.py
+++ b/lldb/test/functionalities/alias/welcome.py
@@ -1,6 +1,10 @@
 import sys
 
 def welcome_impl(debugger, args, result, dict):
+    """
+        Just a docstring for welcome_impl
+        A command that says hello to LLDB users
+    """
     result.Printf('Hello ' + args + ', welcome to LLDB');
     return None;