Add docstrings for the primordial object -- SBDebugger.

The swig "autodoc" feature to remove '*' from 'char *' will be handled by doing
post-processing on the lldb.py module.

llvm-svn: 134524

1 files changed, 103 insertions, 0 deletions

diff --git a/lldb/include/lldb/API/SBDebugger.h b/lldb/include/lldb/API/SBDebugger.h
index 92ea113b57c..bf0fc34dde8 100644
--- a/lldb/include/lldb/API/SBDebugger.h
+++ b/lldb/include/lldb/API/SBDebugger.h
@@ -15,8 +15,111 @@
 
 namespace lldb {
 
+#ifdef SWIG
+%feature("docstring",
+"SBDebugger is the primordial object that creates SBTargets and provides
+access to them.  It also manages the overall debugging experiences.
+
+For example (in example/disasm.py),
+
+import lldb
+import os
+import sys
+
+def disassemble_instructions (insts):
+    for i in insts:
+        print i
+
+...
+
+# Create a new debugger instance
+debugger = lldb.SBDebugger.Create()
+
+# When we step or continue, don't return from the function until the process 
+# stops. We do this by setting the async mode to false.
+debugger.SetAsync (False)
+
+# Create a target from a file and arch
+print 'Creating a target for \'%s\'' % exe
+
+target = debugger.CreateTargetWithFileAndArch (exe, lldb.LLDB_ARCH_DEFAULT)
+
+if target:
+    # If the target is valid set a breakpoint at main
+    main_bp = target.BreakpointCreateByName (fname, target.GetExecutable().GetFilename());
+
+    print main_bp
+
+    # Launch the process. Since we specified synchronous mode, we won't return
+    # from this function until we hit the breakpoint at main
+    process = target.LaunchSimple (None, None, os.getcwd())
+    
+    # Make sure the launch went ok
+    if process:
+        # Print some simple process info
+        state = process.GetState ()
+        print process
+        if state == lldb.eStateStopped:
+            # Get the first thread
+            thread = process.GetThreadAtIndex (0)
+            if thread:
+                # Print some simple thread info
+                print thread
+                # Get the first frame
+                frame = thread.GetFrameAtIndex (0)
+                if frame:
+                    # Print some simple frame info
+                    print frame
+                    function = frame.GetFunction()
+                    # See if we have debug info (a function)
+                    if function:
+                        # We do have a function, print some info for the function
+                        print function
+                        # Now get all instructions for this function and print them
+                        insts = function.GetInstructions(target)
+                        disassemble_instructions (insts)
+                    else:
+                        # See if we have a symbol in the symbol table for where we stopped
+                        symbol = frame.GetSymbol();
+                        if symbol:
+                            # We do have a symbol, print some info for the symbol
+                            print symbol
+                            # Now get all instructions for this symbol and print them
+                            insts = symbol.GetInstructions(target)
+                            disassemble_instructions (insts)
+
+                    registerList = frame.GetRegisters()
+                    print 'Frame registers (size of register set = %d):' % registerList.GetSize()
+                    for value in registerList:
+                        #print value
+                        print '%s (number of children = %d):' % (value.GetName(), value.GetNumChildren())
+                        for child in value:
+                            print 'Name: ', child.GetName(), ' Value: ', child.GetValue(frame)
+
+            print 'Hit the breakpoint at main, enter to continue and wait for program to exit or \'Ctrl-D\'/\'quit\' to terminate the program'
+            next = sys.stdin.readline()
+            if not next or next.rstrip('\n') == 'quit':
+                print 'Terminating the inferior process...'
+                process.Kill()
+            else:
+                # Now continue to the program exit
+                process.Continue()
+                # When we return from the above function we will hopefully be at the
+                # program exit. Print out some process info
+                print process
+        elif state == lldb.eStateExited:
+            print 'Didn\'t hit the breakpoint at main, program has exited...'
+        else:
+            print 'Unexpected process state: %s, killing process...' % debugger.StateAsCString (state)
+            process.Kill()
+"
+         ) SBDebugger;
+#endif
 class SBDebugger
 {
+#ifdef SWIG
+    %feature("autodoc", "1");
+#endif
 public:
 
     static void