[Lldb-commits] [lldb] r134452 - /lldb/trunk/include/lldb/API/SBThread.h

[Johnny Chen]

Author: johnny
Date: Tue Jul  5 19:16:21 2011
New Revision: 134452

URL: http://llvm.org/viewvc/llvm-project?rev=134452&view=rev
Log:
Add a more verbose docstring for SBThread.h.

Modified:
    lldb/trunk/include/lldb/API/SBThread.h

Modified: lldb/trunk/include/lldb/API/SBThread.h
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/include/lldb/API/SBThread.h?rev=134452&r1=134451&r2=134452&view=diff
==============================================================================
--- lldb/trunk/include/lldb/API/SBThread.h (original)
+++ lldb/trunk/include/lldb/API/SBThread.h Tue Jul  5 19:16:21 2011
@@ -20,8 +20,27 @@
 
 #ifdef SWIG
 %feature("docstring",
-         "Represents a thread of execution."
-         " SBProcess contains SBThread(s)."
+"Represents a thread of execution. SBProcess contains SBThread(s).
+
+For example (in test/lldbutil.py),
+
+# ==================================================
+# Utility functions related to Threads and Processes
+# ==================================================
+
+def get_stopped_threads(process, reason):
+    '''Returns the thread(s) with the specified stop reason in a list.
+
+    The list can be empty if no such thread exists.
+    '''
+    threads = []
+    for t in process:
+        if t.GetStopReason() == reason:
+            threads.append(t)
+    return threads
+
+...
+"
          ) SBThread;
 #endif
 class SBThread
@@ -46,27 +65,40 @@
     lldb::StopReason
     GetStopReason();
 
-    // Get the number of words associated with the stop reason.
+#ifdef SWIG
+    %feature("docstring", "
+#endif
+    /// Get the number of words associated with the stop reason.
+    /// See also GetStopReasonDataAtIndex().
+#ifdef SWIG
+    ") GetStopReasonDataCount;
+#endif
     size_t
     GetStopReasonDataCount();
 
+#ifdef SWIG
+    %feature("docstring", "
+#endif
     //--------------------------------------------------------------------------
-    // Get information associated with a stop reason.
-    //
-    // Breakpoint stop reasons will have data that consists of pairs of 
-    // breakpoint IDs followed by the breakpoint location IDs (they always come
-    // in pairs).
-    //
-    // Stop Reason              Count Data Type
-    // ======================== ===== ==========================================
-    // eStopReasonNone          0
-    // eStopReasonTrace         0
-    // eStopReasonBreakpoint    N     duple: {breakpoint id, location id}
-    // eStopReasonWatchpoint    N     duple: {watchpoint id, location id}
-    // eStopReasonSignal        1     unix signal number
-    // eStopReasonException     N     exception data
-    // eStopReasonPlanComplete  0
+    /// Get information associated with a stop reason.
+    ///
+    /// Breakpoint stop reasons will have data that consists of pairs of 
+    /// breakpoint IDs followed by the breakpoint location IDs (they always come
+    /// in pairs).
+    ///
+    /// Stop Reason              Count Data Type
+    /// ======================== ===== =========================================
+    /// eStopReasonNone          0
+    /// eStopReasonTrace         0
+    /// eStopReasonBreakpoint    N     duple: {breakpoint id, location id}
+    /// eStopReasonWatchpoint    N     duple: {watchpoint id, location id}
+    /// eStopReasonSignal        1     unix signal number
+    /// eStopReasonException     N     exception data
+    /// eStopReasonPlanComplete  0
     //--------------------------------------------------------------------------
+#ifdef SWIG
+    ") GetStopReasonDataAtIndex;
+#endif
     uint64_t
     GetStopReasonDataAtIndex(uint32_t idx);
 
@@ -108,27 +140,33 @@
     void
     RunToAddress (lldb::addr_t addr);
 
+#ifdef SWIG
+    %feature("docstring", "
+#endif
     //--------------------------------------------------------------------------
-    // LLDB currently supports process centric debugging which means when any
-    // thread in a process stops, all other threads are stopped. The Suspend()
-    // call here tells our process to suspend a thread and not let it run when
-    // the other threads in a process are allowed to run. So when 
-    // SBProcess::Continue() is called, any threads that aren't suspended will
-    // be allowed to run. If any of the SBThread functions for stepping are 
-    // called (StepOver, StepInto, StepOut, StepInstruction, RunToAddres), the
-    // thread will now be allowed to run and these funtions will simply return.
-    //
-    // Eventually we plan to add support for thread centric debugging where each
-    // thread is controlled individually and each thread would broadcast its
-    // state, but we haven't implemented this yet.
-    // 
-    // Likewise the SBThread::Resume() call will again allow the thread to run
-    // when the process is continued.
-    //
-    // The Suspend() and Resume() functions are not currently reference counted,
-    // if anyone has the need for them to be reference counted, please let us
-    // know.
+    /// LLDB currently supports process centric debugging which means when any
+    /// thread in a process stops, all other threads are stopped. The Suspend()
+    /// call here tells our process to suspend a thread and not let it run when
+    /// the other threads in a process are allowed to run. So when 
+    /// SBProcess::Continue() is called, any threads that aren't suspended will
+    /// be allowed to run. If any of the SBThread functions for stepping are 
+    /// called (StepOver, StepInto, StepOut, StepInstruction, RunToAddres), the
+    /// thread will now be allowed to run and these funtions will simply return.
+    ///
+    /// Eventually we plan to add support for thread centric debugging where
+    /// each thread is controlled individually and each thread would broadcast
+    /// its state, but we haven't implemented this yet.
+    /// 
+    /// Likewise the SBThread::Resume() call will again allow the thread to run
+    /// when the process is continued.
+    ///
+    /// Suspend() and Resume() functions are not currently reference counted, if
+    /// anyone has the need for them to be reference counted, please let us
+    /// know.
     //--------------------------------------------------------------------------
+#ifdef SWIG
+    ") Suspend;
+#endif
     bool
     Suspend();