Fix up some comments to be more explicit. Remove some long-commented out code.

llvm-svn: 238862

lldb/include/lldb/Target/Thread.h

@@ -205,22 +205,23 @@ public:
     void
     SetState (lldb::StateType state);
 
-    lldb::StateType
-    GetResumeState () const
-    {
-        return m_resume_state;
-    }
-    
-    // This sets the "external resume state" of the thread.  If the thread is suspended here, it should never
-    // get scheduled.  Note that just because a thread is marked as "running" does not mean we will let it run in
-    // a given bit of process control.  For instance "step" tries to stay on the selected thread it was issued on,
-    // which may involve suspending other threads temporarily.  This temporary suspension is NOT reflected in the
-    // state set here and reported in GetResumeState.
-    //
-    // If you are just preparing all threads to run, you should not override the threads that are
-    // marked as suspended by the debugger.  In that case, pass override_suspend = false.  If you want
-    // to force the thread to run (e.g. the "thread continue" command, or are resetting the state
-    // (e.g. in SBThread::Resume()), then pass true to override_suspend.
+    //------------------------------------------------------------------
+    /// Sets the USER resume state for this thread.  If you set a thread to suspended with
+    /// this API, it won't take part in any of the arbitration for ShouldResume, and will stay
+    /// suspended even when other threads do get to run.
+    ///
+    /// N.B. This is not the state that is used internally by thread plans to implement
+    /// staying on one thread while stepping over a breakpoint, etc.  The is the
+    /// TemporaryResume state, and if you are implementing some bit of strategy in the stepping
+    /// machinery you should be using that state and not the user resume state.
+    ///
+    /// If you are just preparing all threads to run, you should not override the threads that are
+    /// marked as suspended by the debugger.  In that case, pass override_suspend = false.  If you want
+    /// to force the thread to run (e.g. the "thread continue" command, or are resetting the state
+    /// (e.g. in SBThread::Resume()), then pass true to override_suspend.
+    /// @return
+    ///    The User resume state for this thread.
+    //------------------------------------------------------------------
     void
     SetResumeState (lldb::StateType state, bool override_suspend = false)
     {
@@ -229,6 +230,21 @@ public:
         m_resume_state = state;
     }
 
+    //------------------------------------------------------------------
+    /// Gets the USER resume state for this thread.  This is not the same as what
+    /// this thread is going to do for any particular step, however if this thread
+    /// returns eStateSuspended, then the process control logic will never allow this
+    /// thread to run.
+    ///
+    /// @return
+    ///    The User resume state for this thread.
+    //------------------------------------------------------------------
+    lldb::StateType
+    GetResumeState () const
+    {
+        return m_resume_state;
+    }
+    
     // This function is called on all the threads before "ShouldResume" and
     // "WillResume" in case a thread needs to change its state before the
     // ThreadList polls all the threads to figure out which ones actually

lldb/source/Target/Thread.cpp

@@ -655,11 +655,6 @@ Thread::SetupForResume ()
         // telling the current plan it will resume, since we might change what the current
         // plan is.
 
-//      StopReason stop_reason = lldb::eStopReasonInvalid;
-//      StopInfoSP stop_info_sp = GetStopInfo();
-//      if (stop_info_sp.get())
-//          stop_reason = stop_info_sp->GetStopReason();
-//      if (stop_reason == lldb::eStopReasonBreakpoint)
         lldb::RegisterContextSP reg_ctx_sp (GetRegisterContext());
         if (reg_ctx_sp)
         {
@@ -725,7 +720,7 @@ Thread::ShouldResume (StateType resume_state)
     // the target, 'cause that slows down single stepping.  So assume that if we got to the point where
     // we're about to resume, and we haven't yet had to fetch the stop reason, then it doesn't need to know
     // about the fact that we are resuming...
-        const uint32_t process_stop_id = GetProcess()->GetStopID();
+    const uint32_t process_stop_id = GetProcess()->GetStopID();
     if (m_stop_info_stop_id == process_stop_id &&
         (m_stop_info_sp && m_stop_info_sp->IsValid()))
     {

lldb/source/Target/ThreadList.cpp

@@ -582,6 +582,7 @@ ThreadList::WillResume ()
 
             if (thread_sp == GetSelectedThread())
             {
+                // If the currently selected thread wants to run on its own, always let it.
                 run_only_current_thread = true;
                 run_me_only_list.Clear();
                 run_me_only_list.AddThread (thread_sp);