[lldb] [NFC] Fix swig docstring annotations (llvm#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.

(cherry picked from commit e35fb3f)

Author: jasonmolenda

lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i

@@ -2,34 +2,30 @@
 "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 
         \"empty dirty page list\" (that is, no modified pages in this
         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
         determine if a dirty memory list is available; it will depend
         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();

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,24 +158,24 @@ 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
     successfully loaded.  On failure, return
     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,7 +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", "
+%feature("docstring", "Get default process broadcaster class name (lldb.process)."
+) lldb::SBProcess::GetBroadcasterClass;
+
+
+%feature("docstring", "
     Deallocates the block of memory (previously allocated using
     AllocateMemory) given in the argument."
 ) lldb::SBProcess::DeallocateMemory;

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."

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;