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

lldb/include/lldb/Interpreter/CommandObject.h

@@ -111,6 +111,9 @@ public:
     void
     SetHelpLong (const char * str);
 
+    void
+    SetHelpLong (std::string str);
+
     void
     SetSyntax (const char *str);
 

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 ();

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,

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)

lldb/source/Interpreter/CommandObject.cpp

@@ -128,6 +128,12 @@ CommandObject::SetHelpLong (const char *cstr)
     m_cmd_help_long = cstr;
 }
 
+void
+CommandObject::SetHelpLong (std::string str)
+{
+    m_cmd_help_long = str;
+}
+
 void
 CommandObject::SetSyntax (const char *cstr)
 {

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,

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);
     

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");
 

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;