[lldb][NFC] Add documentation for SBFrame::GetRegisters

[jasonmolenda]

SBFrame::GetRegisters() (and the .registers / .regs extensions in Python) returns an array of register-set's, not registers like you might expect from the API name. Document this.

[jasonmolenda]

not wedded to the specific words I used here, if anyone has an opinion. just want to get something in there.

[llvmbot]

@llvm/pr-subscribers-lldb

Author: Jason Molenda (jasonmolenda)

Changes

SBFrame::GetRegisters() (and the .registers / .regs extensions in Python) returns an array of register-set's, not registers like you might expect from the API name. Document this.

---

Full diff: https://github.com/llvm/llvm-project/pull/125969.diff

2 Files Affected:

• (modified) lldb/bindings/interface/SBFrameDocstrings.i (+16)
• (modified) lldb/bindings/interface/SBFrameExtensions.i (+2-2)

diff --git a/lldb/bindings/interface/SBFrameDocstrings.i b/lldb/bindings/interface/SBFrameDocstrings.i
index 05a876a685a9127..5823d332c4cdd63 100644
--- a/lldb/bindings/interface/SBFrameDocstrings.i
+++ b/lldb/bindings/interface/SBFrameDocstrings.i
@@ -78,6 +78,22 @@ See also SBThread."
     See also GetFunctionName()."
 ) lldb::SBFrame::IsInlined;
 
+%feature("docstring", "
+    Returns an SBValueList which is an array of one or more register
+    sets that exist for this thread.  
+    Each SBValue in the SBValueList represents one register-set. 
+    The first register-set will be the general purpose registers -- 
+    the registers printed by the `register read` command-line lldb, with 
+    no additional arguments.  
+    The register-set SBValue will have a name, e.g. 
+    SBFrame::GetRegisters().GetValueAtIndex(0).GetName() 
+    may be 'General Purpose Registers', but the general purpose 
+    register-set may not use that exact name, it is only a convention 
+    used by some stubs.
+    A register-set SBValue will have children, one child per register 
+    in the register-set."
+) lldb::SBFrame::GetRegisters;
+
 %feature("docstring", "
     Return true if this frame is artificial (e.g a frame synthesized to
     capture a tail call). Local variables may not be available in an artificial
diff --git a/lldb/bindings/interface/SBFrameExtensions.i b/lldb/bindings/interface/SBFrameExtensions.i
index e0472280666ab9c..5c7a63ac53b3ec1 100644
--- a/lldb/bindings/interface/SBFrameExtensions.i
+++ b/lldb/bindings/interface/SBFrameExtensions.i
@@ -87,8 +87,8 @@ STRING_EXTENSION_OUTSIDE(SBFrame)
         args = property(get_arguments, None, doc='''A read only property that returns a list() that contains a collection of lldb.SBValue objects that represent the argument variables in this stack frame.''')
         arguments = property(get_arguments, None, doc='''A read only property that returns a list() that contains a collection of lldb.SBValue objects that represent the argument variables in this stack frame.''')
         statics = property(get_statics, None, doc='''A read only property that returns a list() that contains a collection of lldb.SBValue objects that represent the static variables in this stack frame.''')
-        registers = property(GetRegisters, None, doc='''A read only property that returns a list() that contains a collection of lldb.SBValue objects that represent the CPU registers for this stack frame.''')
-        regs = property(GetRegisters, None, doc='''A read only property that returns a list() that contains a collection of lldb.SBValue objects that represent the CPU registers for this stack frame.''')
+        registers = property(GetRegisters, None, doc='''A read only property that returns a list() of register sets for this thread.  See SBFrame::GetRegisters() for details.''')
+        regs = property(GetRegisters, None, doc='''A read only property that returns a list() of register sets for this thread.  See SBFrame::GetRegisters() for details.''')
         register = property(get_registers_access, None, doc='''A read only property that returns an helper object providing a flattened indexable view of the CPU registers for this stack frame.''')
         reg = property(get_registers_access, None, doc='''A read only property that returns an helper object providing a flattened indexable view of the CPU registers for this stack frame''')
         parent = property(get_parent_frame, None, doc='''A read only property that returns the parent (caller) frame of the current frame.''')

[jimingham]

LGTM with or without my nitpicking...

[jimingham]

Being incredibly picky, I would say "returns the register sets for this thread as a list()". It always returns all the register sets available, which this wording makes a little more clear.

But that's being really picky.

[felipepiovezan]

LGTM! Thanks for improving this, this has fooled me once before 😅

[hawkinsw]

Hope that those little tweaks help! I appreciate the added documentation!

[jasonmolenda]

Hope that those little tweaks help! I appreciate the added documentation!

Great suggestions, thanks!