Clean up docstrings in swig interface files

Summary:
This patch removes the "//----" frames and "///" leading lines from
docstring comments.  We already have code doing transformations like this in
modify-python-lldb.py, but that's a script I'd like to remove. Instead
of running these transformations everytime we run swig, we can just
perform equivalent on its input once.

This patch can be reproduced (e.g. for downstream merges) with the
following "sweet" perl command:

  perl -i -p -e 'BEGIN{ $/ = undef;} s:(" *\n) *//-----*\n:\1:gs; s:^(     *)/// ?:\1:gsm; s:^ *//------*\n( *\n)?( *"):\2:gsm; s: *$::gsm; s:\n *"\):"):gsm' scripts/interface/*.i

This command produces nearly equivalent python files to those produced
by the relevant code in modify-python-lldb.py. The only difference I
noticed is that here I am slightly more agressive in removing trailing
newlines from docstring comments (the python script seems to leave
newlines in class-level docstrings).

Reviewers: amccarth, clayborg, jingham, aprantl

Subscribers: lldb-commits

Differential Revision: https://reviews.llvm.org/D60498

llvm-svn: 358683

1 files changed, 79 insertions, 109 deletions

diff --git a/lldb/scripts/interface/SBThread.i b/lldb/scripts/interface/SBThread.i
index 86ec280de81..e370f56d5e0 100644
--- a/lldb/scripts/interface/SBThread.i
+++ b/lldb/scripts/interface/SBThread.i
@@ -61,13 +61,13 @@ public:
 
     static const char *
     GetBroadcasterClassName ();
-    
+
     static bool
     EventIsThreadEvent (const SBEvent &event);
-    
+
     static SBFrame
     GetStackFrameFromEvent (const SBEvent &event);
-    
+
     static SBThread
     GetThreadFromEvent (const SBEvent &event);
 
@@ -83,56 +83,49 @@ public:
     GetStopReason();
 
     %feature("docstring", "
-    /// Get the number of words associated with the stop reason.
-    /// See also GetStopReasonDataAtIndex().
-    ") GetStopReasonDataCount;
+    Get the number of words associated with the stop reason.
+    See also GetStopReasonDataAtIndex().") GetStopReasonDataCount;
     size_t
     GetStopReasonDataCount();
 
     %feature("docstring", "
-    //--------------------------------------------------------------------------
-    /// Get information associated with a stop reason.
-    ///
-    /// Breakpoint stop reasons will have data that consists of pairs of 
-    /// breakpoint IDs followed by the breakpoint location IDs (they always come
-    /// in pairs).
-    ///
-    /// Stop Reason              Count Data Type
-    /// ======================== ===== =========================================
-    /// eStopReasonNone          0
-    /// eStopReasonTrace         0
-    /// eStopReasonBreakpoint    N     duple: {breakpoint id, location id}
-    /// eStopReasonWatchpoint    1     watchpoint id
-    /// eStopReasonSignal        1     unix signal number
-    /// eStopReasonException     N     exception data
-    /// eStopReasonExec          0
-    /// eStopReasonPlanComplete  0
-    //--------------------------------------------------------------------------
-    ") GetStopReasonDataAtIndex;
+    Get information associated with a stop reason.
+
+    Breakpoint stop reasons will have data that consists of pairs of
+    breakpoint IDs followed by the breakpoint location IDs (they always come
+    in pairs).
+
+    Stop Reason              Count Data Type
+    ======================== ===== =========================================
+    eStopReasonNone          0
+    eStopReasonTrace         0
+    eStopReasonBreakpoint    N     duple: {breakpoint id, location id}
+    eStopReasonWatchpoint    1     watchpoint id
+    eStopReasonSignal        1     unix signal number
+    eStopReasonException     N     exception data
+    eStopReasonExec          0
+    eStopReasonPlanComplete  0") GetStopReasonDataAtIndex;
     uint64_t
     GetStopReasonDataAtIndex(uint32_t idx);
-        
+
     %feature("autodoc", "
     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.
-    ") GetStopReasonExtendedInfoAsJSON;
+    on the stop reason and is currently used only for instrumentation plugins.") GetStopReasonExtendedInfoAsJSON;
     bool
     GetStopReasonExtendedInfoAsJSON (lldb::SBStream &stream);
-    
+
     %feature("autodoc", "
     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.
-    ") GetStopReasonExtendedBacktraces;
+    traces that were involved in a data race or other type of detected issue.") GetStopReasonExtendedBacktraces;
     SBThreadCollection
     GetStopReasonExtendedBacktraces (InstrumentationRuntimeType type);
 
 
     %feature("autodoc", "
     Pass only an (int)length and expect to get a Python string describing the
-    stop reason.
-    ") GetStopDescription;
+    stop reason.") GetStopDescription;
     size_t
     GetStopDescription (char *dst, size_t dst_len);
 
@@ -145,8 +138,7 @@ public:
     lifetime in this process and will not be reused by another thread during this
     process lifetime.  On Mac OS X systems, this is a system-wide unique thread
     identifier; this identifier is also used by other tools like sample which helps
-    to associate data from those tools with lldb.  See related GetIndexID.
-    ")
+    to associate data from those tools with lldb.  See related GetIndexID.")
     GetThreadID;
     lldb::tid_t
     GetThreadID () const;
@@ -158,8 +150,7 @@ public:
     and increments up throughout the process lifetime.  An index number will not be
     reused for a different thread later in a process - thread 1 will always be
     associated with the same thread.  See related GetThreadID.
-    This method returns a uint32_t index number, takes no arguments.
-    ")
+    This method returns a uint32_t index number, takes no arguments.")
     GetIndexID;
     uint32_t
     GetIndexID () const;
@@ -169,29 +160,24 @@ public:
 
     %feature("autodoc", "
     Return the queue name associated with this thread, if any, as a str.
-    For example, with a libdispatch (aka Grand Central Dispatch) queue.
-    ") GetQueueName;
+    For example, with a libdispatch (aka Grand Central Dispatch) queue.") GetQueueName;
 
     const char *
     GetQueueName() const;
 
     %feature("autodoc", "
     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.
-    ") GetQueueID;
+    For example, with a libdispatch (aka Grand Central Dispatch) queue.") GetQueueID;
 
     lldb::queue_id_t
     GetQueueID() const;
 
     %feature("docstring", "
-    //--------------------------------------------------------------------------
-    /// Takes a path string and a SBStream reference as parameters, returns a bool.  
-    /// Collects the thread's 'info' dictionary from the remote system, uses the path
-    /// argument to descend into the dictionary to an item of interest, and prints
-    /// it into the SBStream in a natural format.  Return bool is to indicate if
-    /// anything was printed into the stream (true) or not (false).
-    //--------------------------------------------------------------------------
-    ") GetInfoItemByPathAsString;
+    Takes a path string and a SBStream reference as parameters, returns a bool.
+    Collects the thread's 'info' dictionary from the remote system, uses the path
+    argument to descend into the dictionary to an item of interest, and prints
+    it into the SBStream in a natural format.  Return bool is to indicate if
+    anything was printed into the stream (true) or not (false).") GetInfoItemByPathAsString;
 
     bool
     GetInfoItemByPathAsString (const char *path, lldb::SBStream &strm);
@@ -203,8 +189,7 @@ public:
     and QueueName, but not provide an SBQueue.  Those individual attributes may have
     been saved for the HistoryThread without enough information to reconstitute the
     entire SBQueue at that time.
-    This method takes no arguments, returns an SBQueue.
-    ") GetQueue;
+    This method takes no arguments, returns an SBQueue.") GetQueue;
 
     lldb::SBQueue
     GetQueue () const;
@@ -226,8 +211,7 @@ public:
     %feature("autodoc", "
     Step the current thread from the current source line to the line given by end_line, stopping if
     the thread steps into the function given by target_name.  If target_name is None, then stepping will stop
-    in any of the places we would normally stop.
-    ") StepInto;
+    in any of the places we would normally stop.") StepInto;
     void
     StepInto (const char *target_name,
               uint32_t end_line,
@@ -254,8 +238,7 @@ public:
     StepInstruction(bool step_over);
 
     %feature("autodoc",
-    "Do an instruction level single step in the currently selected thread.
-    ") StepInstruction;
+    "Do an instruction level single step in the currently selected thread.") StepInstruction;
     void
     StepInstruction(bool step_over, SBError &error);
 
@@ -283,55 +266,50 @@ public:
     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.
-    ") ReturnFromFrame;
-    
+    present only scalar return values are supported.") ReturnFromFrame;
+
     SBError
     ReturnFromFrame (SBFrame &frame, SBValue &return_value);
 
     %feature("autodoc", "
     Unwind the stack frames from the innermost expression evaluation.
-    This API is equivalent to 'thread return -x'.
-    ") UnwindInnermostExpression;
-    
+    This API is equivalent to 'thread return -x'.") UnwindInnermostExpression;
+
     SBError
     UnwindInnermostExpression();
 
     %feature("docstring", "
-    //--------------------------------------------------------------------------
-    /// LLDB currently supports process centric debugging which means when any
-    /// thread in a process stops, all other threads are stopped. The Suspend()
-    /// call here tells our process to suspend a thread and not let it run when
-    /// the other threads in a process are allowed to run. So when 
-    /// SBProcess::Continue() is called, any threads that aren't suspended will
-    /// be allowed to run. If any of the SBThread functions for stepping are 
-    /// called (StepOver, StepInto, StepOut, StepInstruction, RunToAddres), the
-    /// thread will now be allowed to run and these functions will simply return.
-    ///
-    /// Eventually we plan to add support for thread centric debugging where
-    /// each thread is controlled individually and each thread would broadcast
-    /// its state, but we haven't implemented this yet.
-    /// 
-    /// Likewise the SBThread::Resume() call will again allow the thread to run
-    /// when the process is continued.
-    ///
-    /// Suspend() and Resume() functions are not currently reference counted, if
-    /// anyone has the need for them to be reference counted, please let us
-    /// know.
-    //--------------------------------------------------------------------------
-    ") Suspend;
+    LLDB currently supports process centric debugging which means when any
+    thread in a process stops, all other threads are stopped. The Suspend()
+    call here tells our process to suspend a thread and not let it run when
+    the other threads in a process are allowed to run. So when
+    SBProcess::Continue() is called, any threads that aren't suspended will
+    be allowed to run. If any of the SBThread functions for stepping are
+    called (StepOver, StepInto, StepOut, StepInstruction, RunToAddres), the
+    thread will now be allowed to run and these functions will simply return.
+
+    Eventually we plan to add support for thread centric debugging where
+    each thread is controlled individually and each thread would broadcast
+    its state, but we haven't implemented this yet.
+
+    Likewise the SBThread::Resume() call will again allow the thread to run
+    when the process is continued.
+
+    Suspend() and Resume() functions are not currently reference counted, if
+    anyone has the need for them to be reference counted, please let us
+    know.") Suspend;
     bool
     Suspend();
 
     bool
     Suspend(SBError &error);
-    
+
     bool
     Resume ();
 
     bool
     Resume (SBError &error);
-    
+
     bool
     IsSuspended();
 
@@ -355,19 +333,16 @@ public:
 
     bool
     GetDescription (lldb::SBStream &description) const;
-    
+
     %feature("docstring", "
-    //--------------------------------------------------------------------------
-    /// Get the description strings for this thread that match what the 
-    /// lldb driver will present, using the thread-format (stop_format==false)
-    /// or thread-stop-format (stop_format = true).
-    //--------------------------------------------------------------------------
-    ") GetDescription;
+    Get the description strings for this thread that match what the
+    lldb driver will present, using the thread-format (stop_format==false)
+    or thread-stop-format (stop_format = true).") GetDescription;
     bool GetDescription(lldb::SBStream &description, bool stop_format) const;
 
     bool
     GetStatus (lldb::SBStream &status) const;
-    
+
     bool
     operator == (const lldb::SBThread &rhs) const;
 
@@ -376,35 +351,32 @@ public:
 
     %feature("autodoc","
     Given an argument of str to specify the type of thread-origin extended
-    backtrace to retrieve, query whether the origin of this thread is 
+    backtrace to retrieve, query whether the origin of this thread is
     available.  An SBThread is retured; SBThread.IsValid will return true
     if an extended backtrace was available.  The returned SBThread is not
     a part of the SBProcess' thread list and it cannot be manipulated like
     normal threads -- you cannot step or resume it, for instance -- it is
     intended to used primarily for generating a backtrace.  You may request
-    the returned thread's own thread origin in turn.
-    ") GetExtendedBacktraceThread;
+    the returned thread's own thread origin in turn.") GetExtendedBacktraceThread;
     lldb::SBThread
     GetExtendedBacktraceThread (const char *type);
 
     %feature("autodoc","
     Takes no arguments, returns a uint32_t.
     If this SBThread is an ExtendedBacktrace thread, get the IndexID of the
-    original thread that this ExtendedBacktrace thread represents, if 
+    original thread that this ExtendedBacktrace thread represents, if
     available.  The thread that was running this backtrace in the past may
     not have been registered with lldb's thread index (if it was created,
     did its work, and was destroyed without lldb ever stopping execution).
-    In that case, this ExtendedBacktrace thread's IndexID will be returned.
-    ") GetExtendedBacktraceOriginatingIndexID;
+    In that case, this ExtendedBacktrace thread's IndexID will be returned.") GetExtendedBacktraceOriginatingIndexID;
     uint32_t
     GetExtendedBacktraceOriginatingIndexID();
-    
+
     %feature("autodoc","
     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.
-    ") GetCurrentException;
+    being processes.") GetCurrentException;
     lldb::SBValue
     GetCurrentException();
 
@@ -412,8 +384,7 @@ public:
     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.
-    ") GetCurrentExceptionBacktrace;
+    even when the program is no longer at the throw site.") GetCurrentExceptionBacktrace;
     lldb::SBThread
     GetCurrentExceptionBacktrace();
 
@@ -422,8 +393,7 @@ public:
     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.
-    ") SafeToCallFunctions;
+    thread.") SafeToCallFunctions;
     bool
     SafeToCallFunctions ();
 
@@ -445,12 +415,12 @@ public:
                 if self.sbthread:
                     return int(self.sbthread.GetNumFrames())
                 return 0
-            
+
             def __getitem__(self, key):
                 if type(key) is int and key < self.sbthread.GetNumFrames():
                     return self.sbthread.GetFrameAtIndex(key)
                 return None
-        
+
         def get_frames_access_object(self):
             '''An accessor function that returns a frames_access() object which allows lazy frame access from a lldb.SBThread object.'''
             return self.frames_access (self)
@@ -461,7 +431,7 @@ public:
             for frame in self:
                 frames.append(frame)
             return frames
-        
+
         __swig_getmethods__["id"] = GetThreadID
         if _newclass: id = property(GetThreadID, None, doc='''A read only property that returns the thread ID as an integer.''')