[Lldb-commits] [lldb] Add docs describing how the thread plan stack affects stepping (PR #110167)

[Felipe de Azevedo Piovezan via lldb-commits]

================
@@ -536,6 +536,33 @@ This command will run the thread in the current frame until it reaches line 100
 in this frame or stops if it leaves the current frame. This is a pretty close
 equivalent to GDB's ``until`` command.
 
+One other useful thing to note about the lldb stepping commands is that they
+are implemented as a stack of interruptible operations.  Until the operation -
+e.g. step to the next line - is completed, the operation will remain on the
+stack.  If it is interrupted, new stepping commands will result in their
+operations being pushed onto the stack, each of them retired as they are completed.
+
+Suppose, for instance, you ``step-over`` a source line, and hit a breakpoint
+in a function called by the code of the line you are stepping over.  Since the step-over
+operation remains on the stack, you can examine the state at
+the point of the breakpoint hit, step around in that frame, step in to other
+frames, hit other breakpoints, etc.  Then when you are done, a simple ``continue``
----------------
felipepiovezan wrote:

Feel free to push on this, but I think the big gap between the cause (1) and effect (2) here can be detrimental to the point you are trying to make:
1) "Since the step-over operation remains on the stack..."  and 2) "when you are done, a simple ``continue`` will resume the original step-over...".

Maybe we could remove the "Since" clause (1) and fold it into 2? Something like:

You can examine [...]. When you are done, _because the step-over operation remains on the stack_, a simple ``continue``...

https://github.com/llvm/llvm-project/pull/110167