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 <jing...@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 <jing...@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
_______________________________________________
lldb-commits mailing list
lldb-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
