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, 120 insertions, 141 deletions

diff --git a/lldb/scripts/interface/SBModule.i b/lldb/scripts/interface/SBModule.i
index e0119db8469..1fe8fcfbc3f 100644
--- a/lldb/scripts/interface/SBModule.i
+++ b/lldb/scripts/interface/SBModule.i
@@ -119,10 +119,10 @@ public:
     SBModule ();
 
     SBModule (const lldb::SBModule &rhs);
-     
+
     SBModule (const lldb::SBModuleSpec &module_spec);
-    
-    SBModule (lldb::SBProcess &process, 
+
+    SBModule (lldb::SBProcess &process,
               lldb::addr_t header_addr);
 
     ~SBModule ();
@@ -136,43 +136,37 @@ public:
     Clear();
 
     %feature("docstring", "
-    //------------------------------------------------------------------
-    /// Get const accessor for the module file specification.
-    ///
-    /// This function returns the file for the module on the host system
-    /// that is running LLDB. This can differ from the path on the 
-    /// platform since we might be doing remote debugging.
-    ///
-    /// @return
-    ///     A const reference to the file specification object.
-    //------------------------------------------------------------------
-    ") GetFileSpec;
+    Get const accessor for the module file specification.
+
+    This function returns the file for the module on the host system
+    that is running LLDB. This can differ from the path on the
+    platform since we might be doing remote debugging.
+
+    @return
+        A const reference to the file specification object.") GetFileSpec;
     lldb::SBFileSpec
     GetFileSpec () const;
 
     %feature("docstring", "
-    //------------------------------------------------------------------
-    /// Get accessor for the module platform file specification.
-    ///
-    /// Platform file refers to the path of the module as it is known on
-    /// the remote system on which it is being debugged. For local 
-    /// debugging this is always the same as Module::GetFileSpec(). But
-    /// remote debugging might mention a file '/usr/lib/liba.dylib'
-    /// which might be locally downloaded and cached. In this case the
-    /// platform file could be something like:
-    /// '/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib'
-    /// The file could also be cached in a local developer kit directory.
-    ///
-    /// @return
-    ///     A const reference to the file specification object.
-    //------------------------------------------------------------------
-    ") GetPlatformFileSpec;
+    Get accessor for the module platform file specification.
+
+    Platform file refers to the path of the module as it is known on
+    the remote system on which it is being debugged. For local
+    debugging this is always the same as Module::GetFileSpec(). But
+    remote debugging might mention a file '/usr/lib/liba.dylib'
+    which might be locally downloaded and cached. In this case the
+    platform file could be something like:
+    '/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib'
+    The file could also be cached in a local developer kit directory.
+
+    @return
+        A const reference to the file specification object.") GetPlatformFileSpec;
     lldb::SBFileSpec
     GetPlatformFileSpec () const;
 
     bool
     SetPlatformFileSpec (const lldb::SBFileSpec &platform_file);
-             
+
     lldb::SBFileSpec
     GetRemoteInstallFileSpec ();
 
@@ -195,7 +189,7 @@ public:
     ResolveFileAddress (lldb::addr_t vm_addr);
 
     lldb::SBSymbolContext
-    ResolveSymbolContextForAddress (const lldb::SBAddress& addr, 
+    ResolveSymbolContextForAddress (const lldb::SBAddress& addr,
                                     uint32_t resolve_scope);
 
     bool
@@ -208,25 +202,22 @@ public:
     GetCompileUnitAtIndex (uint32_t);
 
     %feature("docstring", "
-    //------------------------------------------------------------------
-    /// Find compile units related to *this module and passed source
-    /// file.
-    ///
-    /// @param[in] sb_file_spec
-    ///     A lldb::SBFileSpec object that contains source file
-    ///     specification.
-    ///
-    /// @return
-    ///     A lldb::SBSymbolContextList that gets filled in with all of
-    ///     the symbol contexts for all the matches.
-    //------------------------------------------------------------------
-    ") FindCompileUnits;
+    Find compile units related to *this module and passed source
+    file.
+
+    @param[in] sb_file_spec
+        A lldb::SBFileSpec object that contains source file
+        specification.
+
+    @return
+        A lldb::SBSymbolContextList that gets filled in with all of
+        the symbol contexts for all the matches.") FindCompileUnits;
     lldb::SBSymbolContextList
     FindCompileUnits (const lldb::SBFileSpec &sb_file_spec);
 
     size_t
     GetNumSymbols ();
-    
+
     lldb::SBSymbol
     GetSymbolAtIndex (size_t idx);
 
@@ -237,7 +228,7 @@ public:
     lldb::SBSymbolContextList
     FindSymbols (const char *name,
                  lldb::SymbolType type = eSymbolTypeAny);
-             
+
 
     size_t
     GetNumSections ();
@@ -247,28 +238,25 @@ public:
 
 
     %feature("docstring", "
-    //------------------------------------------------------------------
-    /// Find functions by name.
-    ///
-    /// @param[in] name
-    ///     The name of the function we are looking for.
-    ///
-    /// @param[in] name_type_mask
-    ///     A logical OR of one or more FunctionNameType enum bits that
-    ///     indicate what kind of names should be used when doing the
-    ///     lookup. Bits include fully qualified names, base names,
-    ///     C++ methods, or ObjC selectors. 
-    ///     See FunctionNameType for more details.
-    ///
-    /// @return
-    ///     A symbol context list that gets filled in with all of the
-    ///     matches.
-    //------------------------------------------------------------------
-    ") FindFunctions;
+    Find functions by name.
+
+    @param[in] name
+        The name of the function we are looking for.
+
+    @param[in] name_type_mask
+        A logical OR of one or more FunctionNameType enum bits that
+        indicate what kind of names should be used when doing the
+        lookup. Bits include fully qualified names, base names,
+        C++ methods, or ObjC selectors.
+        See FunctionNameType for more details.
+
+    @return
+        A symbol context list that gets filled in with all of the
+        matches.") FindFunctions;
     lldb::SBSymbolContextList
-    FindFunctions (const char *name, 
+    FindFunctions (const char *name,
                    uint32_t name_type_mask = lldb::eFunctionNameTypeAny);
-    
+
     lldb::SBType
     FindFirstType (const char* name);
 
@@ -282,76 +270,67 @@ public:
     GetBasicType(lldb::BasicType type);
 
     %feature("docstring", "
-    //------------------------------------------------------------------
-    /// Get all types matching \a type_mask from debug info in this
-    /// module.
-    ///
-    /// @param[in] type_mask
-    ///     A bitfield that consists of one or more bits logically OR'ed
-    ///     together from the lldb::TypeClass enumeration. This allows
-    ///     you to request only structure types, or only class, struct
-    ///     and union types. Passing in lldb::eTypeClassAny will return
-    ///     all types found in the debug information for this module.
-    ///
-    /// @return
-    ///     A list of types in this module that match \a type_mask
-    //------------------------------------------------------------------
-    ") GetTypes;
+    Get all types matching \a type_mask from debug info in this
+    module.
+
+    @param[in] type_mask
+        A bitfield that consists of one or more bits logically OR'ed
+        together from the lldb::TypeClass enumeration. This allows
+        you to request only structure types, or only class, struct
+        and union types. Passing in lldb::eTypeClassAny will return
+        all types found in the debug information for this module.
+
+    @return
+        A list of types in this module that match \a type_mask") GetTypes;
     lldb::SBTypeList
     GetTypes (uint32_t type_mask = lldb::eTypeClassAny);
 
     %feature("docstring", "
-    //------------------------------------------------------------------
-    /// Find global and static variables by name.
-    ///
-    /// @param[in] target
-    ///     A valid SBTarget instance representing the debuggee.
-    ///
-    /// @param[in] name
-    ///     The name of the global or static variable we are looking
-    ///     for.
-    ///
-    /// @param[in] max_matches
-    ///     Allow the number of matches to be limited to \a max_matches.
-    ///
-    /// @return
-    ///     A list of matched variables in an SBValueList.
-    //------------------------------------------------------------------
-    ") FindGlobalVariables;
+    Find global and static variables by name.
+
+    @param[in] target
+        A valid SBTarget instance representing the debuggee.
+
+    @param[in] name
+        The name of the global or static variable we are looking
+        for.
+
+    @param[in] max_matches
+        Allow the number of matches to be limited to \a max_matches.
+
+    @return
+        A list of matched variables in an SBValueList.") FindGlobalVariables;
     lldb::SBValueList
-    FindGlobalVariables (lldb::SBTarget &target, 
-                         const char *name, 
+    FindGlobalVariables (lldb::SBTarget &target,
+                         const char *name,
                          uint32_t max_matches);
-    
+
     %feature("docstring", "
-    //------------------------------------------------------------------
-    /// Find the first global (or static) variable by name.
-    ///
-    /// @param[in] target
-    ///     A valid SBTarget instance representing the debuggee.
-    ///
-    /// @param[in] name
-    ///     The name of the global or static variable we are looking
-    ///     for.
-    ///
-    /// @return
-    ///     An SBValue that gets filled in with the found variable (if any).
-    //------------------------------------------------------------------
-    ") FindFirstGlobalVariable;
+    Find the first global (or static) variable by name.
+
+    @param[in] target
+        A valid SBTarget instance representing the debuggee.
+
+    @param[in] name
+        The name of the global or static variable we are looking
+        for.
+
+    @return
+        An SBValue that gets filled in with the found variable (if any).") FindFirstGlobalVariable;
     lldb::SBValue
     FindFirstGlobalVariable (lldb::SBTarget &target, const char *name);
-             
+
     lldb::ByteOrder
     GetByteOrder ();
-    
+
     uint32_t
     GetAddressByteSize();
-    
+
     const char *
     GetTriple ();
-    
+
     uint32_t
-    GetVersion (uint32_t *versions, 
+    GetVersion (uint32_t *versions,
                 uint32_t num_versions);
 
     lldb::SBFileSpec
@@ -365,10 +344,10 @@ public:
 
     bool
     operator == (const lldb::SBModule &rhs) const;
-             
+
     bool
     operator != (const lldb::SBModule &rhs) const;
-             
+
     %pythoncode %{
         def __len__(self):
             '''Return the number of symbols in a lldb.SBModule object.'''
@@ -398,12 +377,12 @@ public:
             '''A helper object that will lazily hand out lldb.SBSymbol objects for a module when supplied an index, name, or regular expression.'''
             def __init__(self, sbmodule):
                 self.sbmodule = sbmodule
-        
+
             def __len__(self):
                 if self.sbmodule:
                     return int(self.sbmodule.GetNumSymbols())
                 return 0
-        
+
             def __getitem__(self, key):
                 count = len(self)
                 if type(key) is int:
@@ -438,15 +417,15 @@ public:
                 else:
                     print("error: unsupported item type: %s" % type(key))
                 return None
-        
+
         def get_symbols_access_object(self):
             '''An accessor function that returns a symbols_access() object which allows lazy symbol access from a lldb.SBModule object.'''
             return self.symbols_access (self)
-        
+
         def get_compile_units_access_object (self):
             '''An accessor function that returns a compile_units_access() object which allows lazy compile unit access from a lldb.SBModule object.'''
             return self.compile_units_access (self)
-        
+
         def get_symbols_array(self):
             '''An accessor function that returns a list() that contains all symbols in a lldb.SBModule object.'''
             symbols = []
@@ -459,12 +438,12 @@ public:
             '''A helper object that will lazily hand out lldb.SBSection objects for a module when supplied an index, name, or regular expression.'''
             def __init__(self, sbmodule):
                 self.sbmodule = sbmodule
-        
+
             def __len__(self):
                 if self.sbmodule:
                     return int(self.sbmodule.GetNumSections())
                 return 0
-        
+
             def __getitem__(self, key):
                 count = len(self)
                 if type(key) is int:
@@ -494,12 +473,12 @@ public:
             '''A helper object that will lazily hand out lldb.SBCompileUnit objects for a module when supplied an index, full or partial path, or regular expression.'''
             def __init__(self, sbmodule):
                 self.sbmodule = sbmodule
-        
+
             def __len__(self):
                 if self.sbmodule:
                     return int(self.sbmodule.GetNumCompileUnits())
                 return 0
-        
+
             def __getitem__(self, key):
                 count = len(self)
                 if type(key) is int:
@@ -532,7 +511,7 @@ public:
         def get_sections_access_object(self):
             '''An accessor function that returns a sections_access() object which allows lazy section array access.'''
             return self.sections_access (self)
-        
+
         def get_sections_array(self):
             '''An accessor function that returns an array object that contains all sections in this module object.'''
             if not hasattr(self, 'sections_array'):
@@ -569,31 +548,31 @@ public:
 
         def get_uuid(self):
             return uuid.UUID (self.GetUUIDString())
-        
+
         __swig_getmethods__["uuid"] = get_uuid
         if _newclass: uuid = property(get_uuid, None, doc='''A read only property that returns a standard python uuid.UUID object that represents the UUID of this module.''')
-        
+
         __swig_getmethods__["file"] = GetFileSpec
         if _newclass: file = property(GetFileSpec, None, doc='''A read only property that returns an lldb object that represents the file (lldb.SBFileSpec) for this object file for this module as it is represented where it is being debugged.''')
-        
+
         __swig_getmethods__["platform_file"] = GetPlatformFileSpec
         if _newclass: platform_file = property(GetPlatformFileSpec, None, doc='''A read only property that returns an lldb object that represents the file (lldb.SBFileSpec) for this object file for this module as it is represented on the current host system.''')
-        
+
         __swig_getmethods__["byte_order"] = GetByteOrder
         if _newclass: byte_order = property(GetByteOrder, None, doc='''A read only property that returns an lldb enumeration value (lldb.eByteOrderLittle, lldb.eByteOrderBig, lldb.eByteOrderInvalid) that represents the byte order for this module.''')
-        
+
         __swig_getmethods__["addr_size"] = GetAddressByteSize
         if _newclass: addr_size = property(GetAddressByteSize, None, doc='''A read only property that returns the size in bytes of an address for this module.''')
-        
+
         __swig_getmethods__["triple"] = GetTriple
         if _newclass: triple = property(GetTriple, None, doc='''A read only property that returns the target triple (arch-vendor-os) for this module.''')
 
         __swig_getmethods__["num_symbols"] = GetNumSymbols
         if _newclass: num_symbols = property(GetNumSymbols, None, doc='''A read only property that returns number of symbols in the module symbol table as an integer.''')
-        
+
         __swig_getmethods__["num_sections"] = GetNumSections
         if _newclass: num_sections = property(GetNumSections, None, doc='''A read only property that returns number of sections in the module as an integer.''')
-        
+
     %}
 
 };