[Lldb-commits] [lldb] [lldb] [NFC] Fix swig docstring annotations (PR #88073)
Jason Molenda via lldb-commits
lldb-commits at lists.llvm.org
Mon Apr 8 17:20:50 PDT 2024
https://github.com/jasonmolenda created https://github.com/llvm/llvm-project/pull/88073
Some of the SB API method description docstrings for swing are annotated as `%feature("autodoc")` - but `"autodoc"` annotations are only to substitute a string showing the arguments and return variables - either in a single line, or in multiple lines. SBMemoryRegionInfo used `"autodoc"` correctly describing the parameters and return type, but then it added a description too which is not correct either.
Change all of these that are adding a method description to use `%feature("docstring")` instead. There were a half dozen instances where `"autodoc"` was correctly being used and we have overriden the parameter and return types with a more readable version.
>From 97f8f87fc4b14a973eb0bb0ac67ff36f1f4ef08a Mon Sep 17 00:00:00 2001
From: Jason Molenda <jason at molenda.com>
Date: Mon, 8 Apr 2024 17:17:16 -0700
Subject: [PATCH] [lldb] [NFC] Fix swig docstring annotations
Some of the SB API method description docstrings for swing are
annotated as `%feature("autodoc")` - but `"autodoc"` annotations
are only to substitute a string showing the arguments and return
variables - either in a single line, or in multiple lines.
SBMemoryRegionInfo used `"autodoc"` correctly describing the
parameters and return type, but then it added a description too
which is not correct either.
Change all of these that are adding a method description to use
`%feature("docstring")` instead. There were a half dozen instances
where `"autodoc"` was correctly being used and we have overriden
the parameter and return types with a more readable version.
---
.../interface/SBMemoryRegionInfoDocstrings.i | 12 ++---
lldb/bindings/interface/SBProcessDocstrings.i | 50 +++++++++----------
lldb/bindings/interface/SBQueueDocstrings.i | 4 +-
lldb/bindings/interface/SBThreadDocstrings.i | 36 +++++++------
4 files changed, 48 insertions(+), 54 deletions(-)
diff --git a/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i b/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
index bd80740f3fdd3b..d7c68baf100e27 100644
--- a/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
+++ b/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
@@ -2,8 +2,7 @@
"API clients can get information about memory regions in processes."
) lldb::SBMemoryRegionInfo;
-%feature("autodoc", "
- GetRegionEnd(SBMemoryRegionInfo self) -> lldb::addr_t
+%feature("docstring", "
Returns whether this memory region has a list of modified (dirty)
pages available or not. When calling GetNumDirtyPages(), you will
have 0 returned for both \"dirty page list is not known\" and
@@ -11,8 +10,7 @@
memory region). You must use this method to disambiguate."
) lldb::SBMemoryRegionInfo::HasDirtyMemoryPageList;
-%feature("autodoc", "
- GetNumDirtyPages(SBMemoryRegionInfo self) -> uint32_t
+%feature("docstring", "
Return the number of dirty (modified) memory pages in this
memory region, if available. You must use the
SBMemoryRegionInfo::HasDirtyMemoryPageList() method to
@@ -20,16 +18,14 @@
on the target system can provide this information."
) lldb::SBMemoryRegionInfo::GetNumDirtyPages;
-%feature("autodoc", "
- GetDirtyPageAddressAtIndex(SBMemoryRegionInfo self, uint32_t idx) -> lldb::addr_t
+%feature("docstring", "
Return the address of a modified, or dirty, page of memory.
If the provided index is out of range, or this memory region
does not have dirty page information, LLDB_INVALID_ADDRESS
is returned."
) lldb::SBMemoryRegionInfo::GetDirtyPageAddressAtIndex;
-%feature("autodoc", "
- GetPageSize(SBMemoryRegionInfo self) -> int
+%feature("docstring", "
Return the size of pages in this memory region. 0 will be returned
if this information was unavailable."
) lldb::SBMemoryRegionInfo::GetPageSize();
diff --git a/lldb/bindings/interface/SBProcessDocstrings.i b/lldb/bindings/interface/SBProcessDocstrings.i
index 3ee17e0c7f2fbb..c20ef3e4655bd4 100644
--- a/lldb/bindings/interface/SBProcessDocstrings.i
+++ b/lldb/bindings/interface/SBProcessDocstrings.i
@@ -20,18 +20,18 @@ SBProcess supports thread iteration. For example (from test/lldbutil.py), ::
"
) lldb::SBProcess;
-%feature("autodoc", "
+%feature("docstring", "
Writes data into the current process's stdin. API client specifies a Python
string as the only argument."
) lldb::SBProcess::PutSTDIN;
-%feature("autodoc", "
+%feature("docstring", "
Reads data from the current process's stdout stream. API client specifies
the size of the buffer to read data into. It returns the byte buffer in a
Python string."
) lldb::SBProcess::GetSTDOUT;
-%feature("autodoc", "
+%feature("docstring", "
Reads data from the current process's stderr stream. API client specifies
the size of the buffer to read data into. It returns the byte buffer in a
Python string."
@@ -47,34 +47,34 @@ SBProcess supports thread iteration. For example (from test/lldbutil.py), ::
"See SBTarget.Launch for argument description and usage."
) lldb::SBProcess::RemoteLaunch;
-%feature("autodoc", "
+%feature("docstring", "
Returns the INDEX'th thread from the list of current threads. The index
of a thread is only valid for the current stop. For a persistent thread
identifier use either the thread ID or the IndexID. See help on SBThread
for more details."
) lldb::SBProcess::GetThreadAtIndex;
-%feature("autodoc", "
+%feature("docstring", "
Returns the thread with the given thread ID."
) lldb::SBProcess::GetThreadByID;
-%feature("autodoc", "
+%feature("docstring", "
Returns the thread with the given thread IndexID."
) lldb::SBProcess::GetThreadByIndexID;
-%feature("autodoc", "
+%feature("docstring", "
Returns the currently selected thread."
) lldb::SBProcess::GetSelectedThread;
-%feature("autodoc", "
+%feature("docstring", "
Lazily create a thread on demand through the current OperatingSystem plug-in, if the current OperatingSystem plug-in supports it."
) lldb::SBProcess::CreateOSPluginThread;
-%feature("autodoc", "
+%feature("docstring", "
Returns the process ID of the process."
) lldb::SBProcess::GetProcessID;
-%feature("autodoc", "
+%feature("docstring", "
Returns an integer ID that is guaranteed to be unique across all process instances. This is not the process ID, just a unique integer for comparison and caching purposes."
) lldb::SBProcess::GetUniqueID;
@@ -95,7 +95,7 @@ SBProcess supports thread iteration. For example (from test/lldbutil.py), ::
will always increase, but may increase by more than one per stop."
) lldb::SBProcess::GetStopID;
-%feature("autodoc", "
+%feature("docstring", "
Reads memory from the current process's address space and removes any
traps that may have been inserted into the memory. It returns the byte
buffer in a Python string. Example: ::
@@ -105,7 +105,7 @@ SBProcess supports thread iteration. For example (from test/lldbutil.py), ::
new_bytes = bytearray(content)"
) lldb::SBProcess::ReadMemory;
-%feature("autodoc", "
+%feature("docstring", "
Writes memory to the current process's address space and maintains any
traps that might be present due to software breakpoints. Example: ::
@@ -116,8 +116,8 @@ SBProcess supports thread iteration. For example (from test/lldbutil.py), ::
print('SBProcess.WriteMemory() failed!')"
) lldb::SBProcess::WriteMemory;
-%feature("autodoc", "
- Reads a NULL terminated C string from the current process's address space.
+%feature("docstring", "
+ Reads a NUL terminated C string from the current process's address space.
It returns a python string of the exact length, or truncates the string if
the maximum character limit is reached. Example: ::
@@ -131,7 +131,7 @@ SBProcess supports thread iteration. For example (from test/lldbutil.py), ::
) lldb::SBProcess::ReadCStringFromMemory;
-%feature("autodoc", "
+%feature("docstring", "
Reads an unsigned integer from memory given a byte size and an address.
Returns the unsigned integer that was read. Example: ::
@@ -145,7 +145,7 @@ SBProcess supports thread iteration. For example (from test/lldbutil.py), ::
) lldb::SBProcess::ReadUnsignedFromMemory;
-%feature("autodoc", "
+%feature("docstring", "
Reads a pointer from memory from an address and returns the value. Example: ::
# Read a pointer from address 0x1000
@@ -158,16 +158,16 @@ SBProcess supports thread iteration. For example (from test/lldbutil.py), ::
) lldb::SBProcess::ReadPointerFromMemory;
-%feature("autodoc", "
+%feature("docstring", "
Returns the implementation object of the process plugin if available. None
otherwise."
) lldb::SBProcess::GetScriptedImplementation;
-%feature("autodoc", "
+%feature("docstring", "
Returns the process' extended crash information."
) lldb::SBProcess::GetExtendedCrashInformation;
-%feature("autodoc", "
+%feature("docstring", "
Load the library whose filename is given by image_spec looking in all the
paths supplied in the paths argument. If successful, return a token that
can be passed to UnloadImage and fill loaded_path with the path that was
@@ -175,7 +175,7 @@ SBProcess supports thread iteration. For example (from test/lldbutil.py), ::
lldb.LLDB_INVALID_IMAGE_TOKEN."
) lldb::SBProcess::LoadImageUsingPaths;
-%feature("autodoc", "
+%feature("docstring", "
Return the number of different thread-origin extended backtraces
this process can support as a uint32_t.
When the process is stopped and you have an SBThread, lldb may be
@@ -184,12 +184,12 @@ SBProcess supports thread iteration. For example (from test/lldbutil.py), ::
queue)."
) lldb::SBProcess::GetNumExtendedBacktraceTypes;
-%feature("autodoc", "
+%feature("docstring", "
Takes an index argument, returns the name of one of the thread-origin
extended backtrace methods as a str."
) lldb::SBProcess::GetExtendedBacktraceTypeAtIndex;
-%feature("autodoc", "
+%feature("docstring", "
Get information about the process.
Valid process info will only be returned when the process is alive,
use IsValid() to check if the info returned is valid. ::
@@ -199,7 +199,7 @@ SBProcess supports thread iteration. For example (from test/lldbutil.py), ::
process_info.GetProcessID()"
) lldb::SBProcess::GetProcessInfo;
-%feature("autodoc", "
+%feature("docstring", "
Allocates a block of memory within the process, with size and
access permissions specified in the arguments. The permissions
argument is an or-combination of zero or more of
@@ -209,11 +209,11 @@ SBProcess supports thread iteration. For example (from test/lldbutil.py), ::
lldb.LLDB_INVALID_ADDRESS if the allocation failed."
) lldb::SBProcess::AllocateMemory;
-%feature("autodoc", "Get default process broadcaster class name (lldb.process)."
+%feature("docstring", "Get default process broadcaster class name (lldb.process)."
) lldb::SBProcess::GetBroadcasterClass;
-%feature("autodoc", "
+%feature("docstring", "
Deallocates the block of memory (previously allocated using
AllocateMemory) given in the argument."
) lldb::SBProcess::DeallocateMemory;
diff --git a/lldb/bindings/interface/SBQueueDocstrings.i b/lldb/bindings/interface/SBQueueDocstrings.i
index fa472d5bed1753..c3baf39a299db9 100644
--- a/lldb/bindings/interface/SBQueueDocstrings.i
+++ b/lldb/bindings/interface/SBQueueDocstrings.i
@@ -2,14 +2,14 @@
"Represents a libdispatch queue in the process."
) lldb::SBQueue;
-%feature("autodoc", "
+%feature("docstring", "
Returns an lldb::queue_id_t type unique identifier number for this
queue that will not be used by any other queue during this process'
execution. These ID numbers often start at 1 with the first
system-created queues and increment from there."
) lldb::SBQueue::GetQueueID;
-%feature("autodoc", "
+%feature("docstring", "
Returns an lldb::QueueKind enumerated value (e.g. eQueueKindUnknown,
eQueueKindSerial, eQueueKindConcurrent) describing the type of this
queue."
diff --git a/lldb/bindings/interface/SBThreadDocstrings.i b/lldb/bindings/interface/SBThreadDocstrings.i
index f307212f0114ed..76822e49c63841 100644
--- a/lldb/bindings/interface/SBThreadDocstrings.i
+++ b/lldb/bindings/interface/SBThreadDocstrings.i
@@ -55,24 +55,24 @@ See also :py:class:`SBFrame` ."
eStopReasonPlanComplete 0"
) lldb::SBThread::GetStopReasonDataAtIndex;
-%feature("autodoc", "
+%feature("docstring", "
Collects a thread's stop reason extended information dictionary and prints it
into the SBStream in a JSON format. The format of this JSON dictionary depends
on the stop reason and is currently used only for instrumentation plugins."
) lldb::SBThread::GetStopReasonExtendedInfoAsJSON;
-%feature("autodoc", "
+%feature("docstring", "
Returns a collection of historical stack traces that are significant to the
current stop reason. Used by ThreadSanitizer, where we provide various stack
traces that were involved in a data race or other type of detected issue."
) lldb::SBThread::GetStopReasonExtendedBacktraces;
-%feature("autodoc", "
+%feature("docstring", "
Pass only an (int)length and expect to get a Python string describing the
stop reason."
) lldb::SBThread::GetStopDescription;
-%feature("autodoc", "
+%feature("docstring", "
Returns a unique thread identifier (type lldb::tid_t, typically a 64-bit type)
for the current SBThread that will remain constant throughout the thread's
lifetime in this process and will not be reused by another thread during this
@@ -81,7 +81,7 @@ See also :py:class:`SBFrame` ."
to associate data from those tools with lldb. See related GetIndexID."
) lldb::SBThread::GetThreadID;
-%feature("autodoc", "
+%feature("docstring", "
Return the index number for this SBThread. The index number is the same thing
that a user gives as an argument to 'thread select' in the command line lldb.
These numbers start at 1 (for the first thread lldb sees in a debug session)
@@ -91,12 +91,12 @@ See also :py:class:`SBFrame` ."
This method returns a uint32_t index number, takes no arguments."
) lldb::SBThread::GetIndexID;
-%feature("autodoc", "
+%feature("docstring", "
Return the queue name associated with this thread, if any, as a str.
For example, with a libdispatch (aka Grand Central Dispatch) queue."
) lldb::SBThread::GetQueueName;
-%feature("autodoc", "
+%feature("docstring", "
Return the dispatch_queue_id for this thread, if any, as a lldb::queue_id_t.
For example, with a libdispatch (aka Grand Central Dispatch) queue."
) lldb::SBThread::GetQueueID;
@@ -109,7 +109,7 @@ See also :py:class:`SBFrame` ."
anything was printed into the stream (true) or not (false)."
) lldb::SBThread::GetInfoItemByPathAsString;
-%feature("autodoc", "
+%feature("docstring", "
Return the SBQueue for this thread. If this thread is not currently associated
with a libdispatch queue, the SBQueue object's IsValid() method will return false.
If this SBThread is actually a HistoryThread, we may be able to provide QueueID
@@ -141,14 +141,14 @@ See also :py:class:`SBFrame` ."
"Do an instruction level single step in the currently selected thread."
) lldb::SBThread::StepInstruction;
-%feature("autodoc", "
+%feature("docstring", "
Force a return from the frame passed in (and any frames younger than it)
without executing any more code in those frames. If return_value contains
a valid SBValue, that will be set as the return value from frame. Note, at
present only scalar return values are supported."
) lldb::SBThread::ReturnFromFrame;
-%feature("autodoc", "
+%feature("docstring", "
Unwind the stack frames from the innermost expression evaluation.
This API is equivalent to 'thread return -x'."
) lldb::SBThread::UnwindInnermostExpression;
@@ -181,7 +181,7 @@ See also :py:class:`SBFrame` ."
or thread-stop-format (stop_format = true)."
) lldb::SBThread::GetDescription;
-%feature("autodoc","
+%feature("docstring","
Given an argument of str to specify the type of thread-origin extended
backtrace to retrieve, query whether the origin of this thread is
available. An SBThread is retured; SBThread.IsValid will return true
@@ -192,8 +192,7 @@ See also :py:class:`SBFrame` ."
the returned thread's own thread origin in turn."
) lldb::SBThread::GetExtendedBacktraceThread;
-%feature("autodoc","
- Takes no arguments, returns a uint32_t.
+%feature("docstring","
If this SBThread is an ExtendedBacktrace thread, get the IndexID of the
original thread that this ExtendedBacktrace thread represents, if
available. The thread that was running this backtrace in the past may
@@ -202,29 +201,28 @@ See also :py:class:`SBFrame` ."
In that case, this ExtendedBacktrace thread's IndexID will be returned."
) lldb::SBThread::GetExtendedBacktraceOriginatingIndexID;
-%feature("autodoc","
+%feature("docstring","
Returns an SBValue object represeting the current exception for the thread,
if there is any. Currently, this works for Obj-C code and returns an SBValue
representing the NSException object at the throw site or that's currently
being processes."
) lldb::SBThread::GetCurrentException;
-%feature("autodoc","
+%feature("docstring","
Returns a historical (fake) SBThread representing the stack trace of an
exception, if there is one for the thread. Currently, this works for Obj-C
code, and can retrieve the throw-site backtrace of an NSException object
even when the program is no longer at the throw site."
) lldb::SBThread::GetCurrentExceptionBacktrace;
-%feature("autodoc","
- Takes no arguments, returns a bool.
+%feature("docstring","
lldb may be able to detect that function calls should not be executed
on a given thread at a particular point in time. It is recommended that
this is checked before performing an inferior function call on a given
thread."
) lldb::SBThread::SafeToCallFunctions;
-%feature("autodoc","
- Retruns a SBValue object representing the siginfo for the current signal.
+%feature("docstring","
+ Returns a SBValue object representing the siginfo for the current signal.
"
) lldb::SBThread::GetSiginfo;
More information about the lldb-commits
mailing list