[Lldb-commits] [lldb] r134560 - in /lldb/trunk/include/lldb/API: SBAddress.h SBFunction.h

[Johnny Chen]

Author: johnny
Date: Wed Jul  6 18:23:53 2011
New Revision: 134560

URL: http://llvm.org/viewvc/llvm-project?rev=134560&view=rev
Log:
Add class docstrings with example usage for SBFunction and SBAddress.

Modified:
    lldb/trunk/include/lldb/API/SBAddress.h
    lldb/trunk/include/lldb/API/SBFunction.h

Modified: lldb/trunk/include/lldb/API/SBAddress.h
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/include/lldb/API/SBAddress.h?rev=134560&r1=134559&r2=134560&view=diff
==============================================================================
--- lldb/trunk/include/lldb/API/SBAddress.h (original)
+++ lldb/trunk/include/lldb/API/SBAddress.h Wed Jul  6 18:23:53 2011
@@ -15,8 +15,47 @@
 
 namespace lldb {
 
+#ifdef SWIG
+%feature("docstring",
+"A section + offset based address class.
+
+The SBAddress class allows addresses to be relative to a section
+that can move during runtime due to images (executables, shared
+libraries, bundles, frameworks) being loaded at different
+addresses than the addresses found in the object file that
+represents them on disk. There are currently two types of addresses
+for a section:
+    o file addresses
+    o load addresses
+
+File addresses represents the virtual addresses that are in the 'on
+disk' object files. These virtual addresses are converted to be
+relative to unique sections scoped to the object file so that
+when/if the addresses slide when the images are loaded/unloaded
+in memory, we can easily track these changes without having to
+update every object (compile unit ranges, line tables, function
+address ranges, lexical block and inlined subroutine address
+ranges, global and static variables) each time an image is loaded or
+unloaded.
+
+Load addresses represents the virtual addresses where each section
+ends up getting loaded at runtime. Before executing a program, it
+is common for all of the load addresses to be unresolved. When a
+DynamicLoader plug-in receives notification that shared libraries
+have been loaded/unloaded, the load addresses of the main executable
+and any images (shared libraries) will be  resolved/unresolved. When
+this happens, breakpoints that are in one of these sections can be
+set/cleared.
+
+See docstring of SBFunction for example usage of SBAddress.
+"
+         ) SBAddress;
+#endif
 class SBAddress
 {
+#ifdef SWIG
+    %feature("autodoc", "1");
+#endif
 public:
 
     SBAddress ();

Modified: lldb/trunk/include/lldb/API/SBFunction.h
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/include/lldb/API/SBFunction.h?rev=134560&r1=134559&r2=134560&view=diff
==============================================================================
--- lldb/trunk/include/lldb/API/SBFunction.h (original)
+++ lldb/trunk/include/lldb/API/SBFunction.h Wed Jul  6 18:23:53 2011
@@ -18,7 +18,40 @@
 
 #ifdef SWIG
 %feature("docstring",
-         "Represents a generic function, which can be inlined or not."
+"Represents a generic function, which can be inlined or not.
+
+For example (in test/lldbutil.py, but slightly modified for doc purpose),
+
+        ...
+
+        frame = thread.GetFrameAtIndex(i)
+        addr = frame.GetPCAddress()
+        load_addr = addr.GetLoadAddress(target)
+        function = frame.GetFunction()
+        mod_name = frame.GetModule().GetFileSpec().GetFilename()
+
+        if not function:
+            # No debug info for 'function'.
+            symbol = frame.GetSymbol()
+            file_addr = addr.GetFileAddress()
+            start_addr = symbol.GetStartAddress().GetFileAddress()
+            symbol_name = symbol.GetName()
+            symbol_offset = file_addr - start_addr
+            print >> output, '  frame #{num}: {addr:#016x} {mod}`{symbol} + {offset}'.format(
+                num=i, addr=load_addr, mod=mod_name, symbol=symbol_name, offset=symbol_offset)
+        else:
+            # Debug info is available for 'function'.
+            func_name = frame.GetFunctionName()
+            file_name = frame.GetLineEntry().GetFileSpec().GetFilename()
+            line_num = frame.GetLineEntry().GetLine()
+            print >> output, '  frame #{num}: {addr:#016x} {mod}`{func} at {file}:{line} {args}'.format(
+                num=i, addr=load_addr, mod=mod_name,
+                func='%s [inlined]' % func_name] if frame.IsInlined() else func_name,
+                file=file_name, line=line_num, args=get_args_as_string(frame, showFuncName=False))
+
+        ...
+
+"
          ) SBFunction;
 #endif
 class SBFunction