[Lldb-commits] [lldb] Add doc strings for SBValue::IsValid and SBValue::GetError. (PR #94007)

[via lldb-commits]

https://github.com/jimingham updated https://github.com/llvm/llvm-project/pull/94007

>From e024ea45c052411f2e7284c0ef5a6d048681cad7 Mon Sep 17 00:00:00 2001
From: Jim Ingham <jingham at apple.com>
Date: Fri, 31 May 2024 11:29:27 -0700
Subject: [PATCH 1/2] Add doc strings for SBValue::IsValid and
 SBValue::GetError.

The IsValid API is actually quite weak - it means "this value can't
answer any questions meaningfully." But I've run into a couple cases
where people thought it meant "was able to reconstruct the value on
this stop" which it does not mean.
These additions should clear that up.
---
 lldb/bindings/interface/SBValueDocstrings.i | 30 +++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/lldb/bindings/interface/SBValueDocstrings.i b/lldb/bindings/interface/SBValueDocstrings.i
index 59fa807f5ec95..7abbfe58dc5ea 100644
--- a/lldb/bindings/interface/SBValueDocstrings.i
+++ b/lldb/bindings/interface/SBValueDocstrings.i
@@ -45,6 +45,36 @@ SBValue instance which interprets the value object as representing the head of a
 linked list."
 ) lldb::SBValue;
 
+%feature("docstring", "
+Returns true if the SBValue holds any useful state
+and false otherwise.
+IsValid is a very weak API, lldb will only return
+invalid SBValues if it has no useful information
+about the SBValue.
+The two main ways you will end up with an invalid
+SBValue are:
+1) default constructed SBValues are not valid.
+2) SBValues that have outlived their SBTarget are
+no longer valid since its not safe to ask them
+questions.
+"
+) lldb::SBValue::IsValid
+
+%feature("docstring", "
+SBValues use the lldb::SBError object returned by
+this API to report construction errors when the SBValue
+is made; and on each stop, the SBError will tell you
+whether lldb could successfully determine the value for
+this program entity represented by this SBValue.
+
+For instance, if you made an SBValue to
+represent a local variable, and then stepped to a PC where
+the variable was unavailable due to optimization, then
+GetError().Success() will be false for this stop, and the
+error string will have more information about the failure.
+"
+) lldb::SBValue::GetError
+
 %feature("docstring", "
     Get a child value by index from a value.
 

>From 3311076fcb264ef2ecd1cd3bf9360dc5201666c5 Mon Sep 17 00:00:00 2001
From: Jim Ingham <jingham at apple.com>
Date: Fri, 31 May 2024 16:02:51 -0700
Subject: [PATCH 2/2] Respond to review comments.

---
 lldb/bindings/interface/SBValueDocstrings.i | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/lldb/bindings/interface/SBValueDocstrings.i b/lldb/bindings/interface/SBValueDocstrings.i
index 7abbfe58dc5ea..ad73fafb20255 100644
--- a/lldb/bindings/interface/SBValueDocstrings.i
+++ b/lldb/bindings/interface/SBValueDocstrings.i
@@ -48,24 +48,26 @@ linked list."
 %feature("docstring", "
 Returns true if the SBValue holds any useful state
 and false otherwise.
-IsValid is a very weak API, lldb will only return
+IsValid is a very limited API, lldb will only return
 invalid SBValues if it has no useful information
 about the SBValue.
 The two main ways you will end up with an invalid
 SBValue are:
 1) default constructed SBValues are not valid.
 2) SBValues that have outlived their SBTarget are
-no longer valid since its not safe to ask them
-questions.
+no longer valid since it would not be safe to ask them
+questions. lldb will instead return a default constructed
+return value.  You can tell why this is happening by
+checking IsValid.
 "
 ) lldb::SBValue::IsValid
 
 %feature("docstring", "
-SBValues use the lldb::SBError object returned by
-this API to report construction errors when the SBValue
-is made; and on each stop, the SBError will tell you
-whether lldb could successfully determine the value for
-this program entity represented by this SBValue.
+Returns an lldb::SBError object that reports
+any construction errors when the SBValue
+is made; and on each stop thereafter, the SBError will be updated 
+to report whether lldb could successfully determine the value for
+the program entity represented by this SBValue.
 
 For instance, if you made an SBValue to
 represent a local variable, and then stepped to a PC where