[lldb][docs] Translate ASCII art to restructured text formatting

This translates most of the old ASCII art in our documentation to the
equivalent in restructured text (which the new version of the LLDB docs
is using).

lldb/bindings/interface/SBAddress.i

@@ -17,8 +17,9 @@ 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
+* load addresses
 
 File addresses represents the virtual addresses that are in the 'on
 disk' object files. These virtual addresses are converted to be

lldb/bindings/interface/SBBreakpoint.i

@@ -11,7 +11,7 @@ namespace lldb {
 "Represents a logical breakpoint and its associated settings.
 
 For example (from test/functionalities/breakpoint/breakpoint_ignore_count/
-TestBreakpointIgnoreCount.py),
+TestBreakpointIgnoreCount.py),::
 
     def breakpoint_ignore_count_python(self):
         '''Use Python APIs to set breakpoint ignore count.'''
@@ -62,13 +62,13 @@ TestBreakpointIgnoreCount.py),
 
         process.Continue()
 
-SBBreakpoint supports breakpoint location iteration, for example,
+SBBreakpoint supports breakpoint location iteration, for example,::
 
     for bl in breakpoint:
         print('breakpoint location load addr: %s' % hex(bl.GetLoadAddress()))
         print('breakpoint location condition: %s' % hex(bl.GetCondition()))
 
-and rich comparison methods which allow the API program to use,
+and rich comparison methods which allow the API program to use,::
 
     if aBreakpoint == bBreakpoint:
         ...
@@ -102,7 +102,7 @@ public:
 
     lldb::SBTarget
     GetTarget() const;
-  
+
     lldb::SBBreakpointLocation
     FindLocationByAddress (lldb::addr_t vm_addr);
 

lldb/bindings/interface/SBBreakpointLocation.i

@@ -15,7 +15,7 @@ A breakpoint location is defined by the breakpoint that produces it,
 and the address that resulted in this particular instantiation.
 Each breakpoint location has its settable options.
 
-SBBreakpoint contains SBBreakpointLocation(s). See docstring of SBBreakpoint
+:py:class:`SBBreakpoint` contains SBBreakpointLocation(s). See docstring of SBBreakpoint
 for retrieval of an SBBreakpointLocation from an SBBreakpoint."
 ) SBBreakpointLocation;
 class SBBreakpointLocation

lldb/bindings/interface/SBBreakpointName.i

@@ -8,12 +8,12 @@
 
 namespace lldb {
 %feature("docstring",
-"Represents a breakpoint name registered in a given SBTarget.
+"Represents a breakpoint name registered in a given :py:class:`SBTarget`.
 
 Breakpoint names provide a way to act on groups of breakpoints.  When you add a
 name to a group of breakpoints, you can then use the name in all the command
 line lldb commands for that name.  You can also configure the SBBreakpointName
-options and those options will be propagated to any SBBreakpoints currently
+options and those options will be propagated to any :py:class:`SBBreakpoint` s currently
 using that name.  Adding a name to a breakpoint will also apply any of the
 set options to that breakpoint.
 

lldb/bindings/interface/SBCommandInterpreter.i

@@ -9,9 +9,11 @@
 namespace lldb {
 
 %feature("docstring",
-"SBCommandInterpreter handles/interprets commands for lldb.  You get the
-command interpreter from the SBDebugger instance. For example (from test/
-python_api/interpreter/TestCommandInterpreterAPI.py),
+"SBCommandInterpreter handles/interprets commands for lldb.
+
+You get the command interpreter from the :py:class:`SBDebugger` instance.
+
+For example (from test/ python_api/interpreter/TestCommandInterpreterAPI.py),::
 
     def command_interpreter_api(self):
         '''Test the SBCommandInterpreter APIs.'''

lldb/bindings/interface/SBCommandInterpreterRunOptions.i

@@ -10,13 +10,14 @@ namespace lldb {
 
 %feature("docstring",
 "SBCommandInterpreterRunOptions controls how the RunCommandInterpreter runs the code it is fed.
+
 A default SBCommandInterpreterRunOptions object has:
-    StopOnContinue: false
-    StopOnError:    false
-    StopOnCrash:    false
-    EchoCommands:   true
-    PrintResults:   true
-    AddToHistory:   true
+* StopOnContinue: false
+* StopOnError:    false
+* StopOnCrash:    false
+* EchoCommands:   true
+* PrintResults:   true
+* AddToHistory:   true
 
 ") SBCommandInterpreterRunOptions;
 class SBCommandInterpreterRunOptions

lldb/bindings/interface/SBCommandReturnObject.i

@@ -10,10 +10,10 @@ namespace lldb {
 
 %feature("docstring",
 "Represents a container which holds the result from command execution.
-It works with SBCommandInterpreter.HandleCommand() to encapsulate the result
+It works with :py:class:`SBCommandInterpreter.HandleCommand()` to encapsulate the result
 of command execution.
 
-See SBCommandInterpreter for example usage of SBCommandReturnObject."
+See :py:class:`SBCommandInterpreter` for example usage of SBCommandReturnObject."
 ) SBCommandReturnObject;
 class SBCommandReturnObject
 {

lldb/bindings/interface/SBCompileUnit.i

@@ -11,7 +11,7 @@ namespace lldb {
 %feature("docstring",
 "Represents a compilation unit, or compiled source file.
 
-SBCompileUnit supports line entry iteration. For example,
+SBCompileUnit supports line entry iteration. For example,::
 
     # Now get the SBSymbolContext from this frame.  We want everything. :-)
     context = frame0.GetSymbolContext(lldb.eSymbolContextEverything)
@@ -25,23 +25,23 @@ SBCompileUnit supports line entry iteration. For example,
         print('start addr: %s' % str(lineEntry.GetStartAddress()))
         print('end   addr: %s' % str(lineEntry.GetEndAddress()))
 
-produces:
-
-line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:20
-start addr: a.out[0x100000d98]
-end   addr: a.out[0x100000da3]
-line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:21
-start addr: a.out[0x100000da3]
-end   addr: a.out[0x100000da9]
-line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:22
-start addr: a.out[0x100000da9]
-end   addr: a.out[0x100000db6]
-line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:23
-start addr: a.out[0x100000db6]
-end   addr: a.out[0x100000dbc]
-...
-
-See also SBSymbolContext and SBLineEntry"
+produces: ::
+
+  line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:20
+  start addr: a.out[0x100000d98]
+  end   addr: a.out[0x100000da3]
+  line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:21
+  start addr: a.out[0x100000da3]
+  end   addr: a.out[0x100000da9]
+  line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:22
+  start addr: a.out[0x100000da9]
+  end   addr: a.out[0x100000db6]
+  line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:23
+  start addr: a.out[0x100000db6]
+  end   addr: a.out[0x100000dbc]
+  ...
+
+See also :py:class:`SBSymbolContext` and :py:class:`SBLineEntry`"
 ) SBCompileUnit;
 class SBCompileUnit
 {

lldb/bindings/interface/SBEnvironment.i

@@ -11,7 +11,8 @@ namespace lldb {
 %feature("docstring",
 "Represents the environment of a certain process.
 
-Example:
+Example: ::
+
   for entry in lldb.debugger.GetSelectedTarget().GetEnvironment().GetEntries():
     print(entry)
 

lldb/bindings/interface/SBError.i

@@ -11,7 +11,7 @@ namespace lldb {
 %feature("docstring",
 "Represents a container for holding any error code.
 
-For example (from test/python_api/hello_world/TestHelloWorld.py),
+For example (from test/python_api/hello_world/TestHelloWorld.py), ::
 
     def hello_world_attach_with_id_api(self):
         '''Create target, spawn a process, and attach to it by id.'''
@@ -45,7 +45,7 @@ For example (from test/python_api/hello_world/TestHelloWorld.py),
 checks that after the attach, there is no error condition by asserting
 that error.Success() is True and we get back a valid process object.
 
-And (from test/python_api/event/TestEvent.py),
+And (from test/python_api/event/TestEvent.py), ::
 
         # Now launch the process, and do not stop at entry point.
         error = lldb.SBError()

lldb/bindings/interface/SBEvent.i

@@ -13,27 +13,27 @@ class SBBroadcaster;
 %feature("docstring",
 "API clients can register to receive events.
 
-For example, check out the following output:
+For example, check out the following output: ::
 
-Try wait for event...
-Event description: 0x103d0bb70 Event: broadcaster = 0x1009c8410, type = 0x00000001, data = { process = 0x1009c8400 (pid = 21528), state = running}
-Event data flavor: Process::ProcessEventData
-Process state: running
+    Try wait for event...
+    Event description: 0x103d0bb70 Event: broadcaster = 0x1009c8410, type = 0x00000001, data = { process = 0x1009c8400 (pid = 21528), state = running}
+    Event data flavor: Process::ProcessEventData
+    Process state: running
 
-Try wait for event...
-Event description: 0x103a700a0 Event: broadcaster = 0x1009c8410, type = 0x00000001, data = { process = 0x1009c8400 (pid = 21528), state = stopped}
-Event data flavor: Process::ProcessEventData
-Process state: stopped
+    Try wait for event...
+    Event description: 0x103a700a0 Event: broadcaster = 0x1009c8410, type = 0x00000001, data = { process = 0x1009c8400 (pid = 21528), state = stopped}
+    Event data flavor: Process::ProcessEventData
+    Process state: stopped
 
-Try wait for event...
-Event description: 0x103d0d4a0 Event: broadcaster = 0x1009c8410, type = 0x00000001, data = { process = 0x1009c8400 (pid = 21528), state = exited}
-Event data flavor: Process::ProcessEventData
-Process state: exited
+    Try wait for event...
+    Event description: 0x103d0d4a0 Event: broadcaster = 0x1009c8410, type = 0x00000001, data = { process = 0x1009c8400 (pid = 21528), state = exited}
+    Event data flavor: Process::ProcessEventData
+    Process state: exited
 
-Try wait for event...
-timeout occurred waiting for event...
+    Try wait for event...
+    timeout occurred waiting for event...
 
-from test/python_api/event/TestEventspy:
+from test/python_api/event/TestEventspy: ::
 
     def do_listen_for_and_print_event(self):
         '''Create a listener and use SBEvent API to print the events received.'''

lldb/bindings/interface/SBFileSpec.i

@@ -13,7 +13,7 @@ namespace lldb {
 basename.  The string values of the paths are put into uniqued string pools
 for fast comparisons and efficient memory usage.
 
-For example, the following code
+For example, the following code ::
 
         lineEntry = context.GetLineEntry()
         self.expect(lineEntry.GetFileSpec().GetDirectory(), 'The line entry should have the correct directory',

lldb/bindings/interface/SBFrame.i

@@ -10,7 +10,7 @@ namespace lldb {
 
 %feature("docstring",
 "Represents one of the stack frames associated with a thread.
-SBThread contains SBFrame(s). For example (from test/lldbutil.py),
+SBThread contains SBFrame(s). For example (from test/lldbutil.py), ::
 
 def print_stacktrace(thread, string_buffer = False):
     '''Prints a simple stack trace of this thread.'''
@@ -37,7 +37,7 @@ def print_stacktrace(thread, string_buffer = False):
 
     ...
 
-And,
+And, ::
 
     for frame in thread:
         print frame

lldb/bindings/interface/SBFunction.i

@@ -11,7 +11,7 @@ namespace lldb {
 %feature("docstring",
 "Represents a generic function, which can be inlined or not.
 
-For example (from test/lldbutil.py, but slightly modified for doc purpose),
+For example (from test/lldbutil.py, but slightly modified for doc purpose),::
 
         ...
 

lldb/bindings/interface/SBInstructionList.i

@@ -14,12 +14,12 @@ namespace lldb {
 "Represents a list of machine instructions.  SBFunction and SBSymbol have
 GetInstructions() methods which return SBInstructionList instances.
 
-SBInstructionList supports instruction (SBInstruction instance) iteration.
-For example (see also SBDebugger for a more complete example),
+SBInstructionList supports instruction (:py:class:`SBInstruction` instance) iteration.
+For example (see also :py:class:`SBDebugger` for a more complete example), ::
 
-def disassemble_instructions (insts):
-    for i in insts:
-        print i
+    def disassemble_instructions (insts):
+        for i in insts:
+            print i
 
 defines a function which takes an SBInstructionList instance and prints out
 the machine instructions in assembly format."

lldb/bindings/interface/SBLineEntry.i

@@ -10,31 +10,31 @@ namespace lldb {
 
 %feature("docstring",
 "Specifies an association with a contiguous range of instructions and
-a source file location. SBCompileUnit contains SBLineEntry(s). For example,
+a source file location. :py:class:`SBCompileUnit` contains SBLineEntry(s). For example, ::
 
     for lineEntry in compileUnit:
         print('line entry: %s:%d' % (str(lineEntry.GetFileSpec()),
                                     lineEntry.GetLine()))
         print('start addr: %s' % str(lineEntry.GetStartAddress()))
         print('end   addr: %s' % str(lineEntry.GetEndAddress()))
 
-produces:
-
-line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:20
-start addr: a.out[0x100000d98]
-end   addr: a.out[0x100000da3]
-line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:21
-start addr: a.out[0x100000da3]
-end   addr: a.out[0x100000da9]
-line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:22
-start addr: a.out[0x100000da9]
-end   addr: a.out[0x100000db6]
-line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:23
-start addr: a.out[0x100000db6]
-end   addr: a.out[0x100000dbc]
-...
-
-See also SBCompileUnit."
+produces: ::
+
+    line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:20
+    start addr: a.out[0x100000d98]
+    end   addr: a.out[0x100000da3]
+    line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:21
+    start addr: a.out[0x100000da3]
+    end   addr: a.out[0x100000da9]
+    line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:22
+    start addr: a.out[0x100000da9]
+    end   addr: a.out[0x100000db6]
+    line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:23
+    start addr: a.out[0x100000db6]
+    end   addr: a.out[0x100000dbc]
+    ...
+
+See also :py:class:`SBCompileUnit` ."
 ) SBLineEntry;
 class SBLineEntry
 {

lldb/bindings/interface/SBListener.i

@@ -11,7 +11,7 @@ namespace lldb {
 %feature("docstring",
 "API clients can register its own listener to debugger events.
 
-See aslo SBEvent for example usage of creating and adding a listener."
+See aslo :py:class:`SBEvent` for example usage of creating and adding a listener."
 ) SBListener;
 class SBListener
 {

lldb/bindings/interface/SBModule.i

@@ -40,30 +40,30 @@ The module is designed to be able to select a single slice of an
 executable image as it would appear on disk and during program
 execution.
 
-You can retrieve SBModule from SBSymbolContext, which in turn is available
+You can retrieve SBModule from :py:class:`SBSymbolContext` , which in turn is available
 from SBFrame.
 
-SBModule supports symbol iteration, for example,
+SBModule supports symbol iteration, for example, ::
 
     for symbol in module:
         name = symbol.GetName()
         saddr = symbol.GetStartAddress()
         eaddr = symbol.GetEndAddress()
 
-and rich comparison methods which allow the API program to use,
+and rich comparison methods which allow the API program to use, ::
 
     if thisModule == thatModule:
         print('This module is the same as that module')
 
 to test module equality.  A module also contains object file sections, namely
-SBSection.  SBModule supports section iteration through section_iter(), for
-example,
+:py:class:`SBSection` .  SBModule supports section iteration through section_iter(), for
+example, ::
 
     print('Number of sections: %d' % module.GetNumSections())
     for sec in module.section_iter():
         print(sec)
 
-And to iterate the symbols within a SBSection, use symbol_in_section_iter(),
+And to iterate the symbols within a SBSection, use symbol_in_section_iter(), ::
 
     # Iterates the text section and prints each symbols within each sub-section.
     for subsec in text_sec:
@@ -72,7 +72,7 @@ And to iterate the symbols within a SBSection, use symbol_in_section_iter(),
             print(INDENT2 + repr(sym))
             print(INDENT2 + 'symbol type: %s' % symbol_type_to_str(sym.GetType()))
 
-produces this following output:
+produces this following output: ::
 
     [0x0000000100001780-0x0000000100001d5c) a.out.__TEXT.__text
         id = {0x00000004}, name = 'mask_access(MaskAction, unsigned int)', range = [0x00000001000017c0-0x0000000100001870)