Add a CLEANUP_DOCSTRING state to our FSM to do cleanup of the Python docstrings

generated from the swig docstring features instead of blindly applying the
cleanup action for all input lines.

llvm-svn: 134368

lldb/scripts/Python/modify-python-lldb.py

@@ -10,7 +10,8 @@
 # swig.  For an example, take a look at SBTarget.h header file, where we take
 # advantage of the already existing doxygen C++-docblock and make it the Python
 # docstring for the same method.  The 'residues' in this context include the
-# '#endif' and the '#ifdef SWIG' lines.
+# '#endif', the '#ifdef SWIG', the c comment marker, the trailing blank (SPC's)
+# line, and the doxygen comment start marker.
 #
 # It also calls SBDebugger.Initialize() to initialize the lldb debugger
 # subsystem.
@@ -32,6 +33,9 @@ c_comment_marker = "//------------"
 trailing_blank_line = '            '
 # The pattern for recognizing the doxygen comment block line.
 doxygen_comment_start = re.compile("^\s*(    /// ?)")
+# The demarcation point for turning on/off residue removal state.
+# When bracketed by the lines, the CLEANUP_DOCSTRING state (see below) is ON.
+toggle_docstring_cleanup_line = '        """'
 
 #
 # lldb_iter() should appear before our first SB* class definition.
@@ -143,6 +147,7 @@ isvalid_pattern = re.compile("^    def IsValid\(")
 NORMAL = 0
 DEFINING_ITERATOR = 1
 DEFINING_EQUALITY = 2
+CLEANUP_DOCSTRING = 4
 
 # The lldb_iter_def only needs to be inserted once.
 lldb_iter_defined = False;
@@ -157,23 +162,25 @@ lldb_iter_defined = False;
 # method definition in order to insert the appropriate method(s) into the lldb
 # module.
 #
+# The state CLEANUP_DOCSTRING can be entered from either the NORMAL or the
+# DEFINING_ITERATOR/EQUALITY states.  While in this state, the FSM is fixing/
+# cleaning the Python docstrings generated by the swig docstring features.
+#
 # The FSM, in all possible states, also checks the current input for IsValid()
 # definition, and inserts a __nonzero__() method definition to implement truth
 # value testing and the built-in operation bool().
 state = NORMAL
 for line in content.splitlines():
-    # Cleanse the lldb.py of the autodoc'ed residues.
-    if c_ifdef_swig in line or c_endif_swig in line:
-        continue
-    # As well as the comment marker line and trailing blank line.
-    if c_comment_marker in line or line == trailing_blank_line:
-        continue
-    # Also remove the '\a ' substrings.
-    line = line.replace('\a ', '')
-    # And the leading '///' substring.
-    doxygen_comment_match = doxygen_comment_start.match(line)
-    if doxygen_comment_match:
-        line = line.replace(doxygen_comment_match.group(1), '', 1)
+    # Handle the state transition into CLEANUP_DOCSTRING state as it is possible
+    # to enter this state from either NORMAL or DEFINING_ITERATOR/EQUALITY.
+    #
+    # If '        """' is the sole line, prepare to transition to the
+    # CLEANUP_DOCSTRING state or out of it.
+    if line == toggle_docstring_cleanup_line:
+        if state & CLEANUP_DOCSTRING:
+            state ^= CLEANUP_DOCSTRING
+        else:
+            state |= CLEANUP_DOCSTRING
 
     if state == NORMAL:
         match = class_pattern.search(line)
@@ -189,11 +196,12 @@ for line in content.splitlines():
             cls = match.group(1)
             if cls in d:
                 # Adding support for iteration for the matched SB class.
-                state = (state | DEFINING_ITERATOR)
+                state |= DEFINING_ITERATOR
             if cls in e:
                 # Adding support for eq and ne for the matched SB class.
-                state = (state | DEFINING_EQUALITY)
-    elif state > NORMAL:
+                state |= DEFINING_EQUALITY
+
+    elif (state & DEFINING_ITERATOR) or (state & DEFINING_EQUALITY):
         match = init_pattern.search(line)
         if match:
             # We found the beginning of the __init__ method definition.
@@ -214,6 +222,23 @@ for line in content.splitlines():
             # Next state will be NORMAL.
             state = NORMAL
 
+    elif (state & CLEANUP_DOCSTRING):
+        # Cleanse the lldb.py of the autodoc'ed residues.
+        if c_ifdef_swig in line or c_endif_swig in line:
+            continue
+        # As well as the comment marker line and trailing blank line.
+        if c_comment_marker in line or line == trailing_blank_line:
+            continue
+        # Also remove the '\a ' substrings.
+        line = line.replace('\a ', '')
+        # And the leading '///' substring.
+        doxygen_comment_match = doxygen_comment_start.match(line)
+        if doxygen_comment_match:
+            line = line.replace(doxygen_comment_match.group(1), '', 1)
+
+        # Note that the transition out of CLEANUP_DOCSTRING is handled at the
+        # beginning of this function already.
+
     # Look for 'def IsValid(*args):', and once located, add implementation
     # of truth value testing for this object by delegation.
     if isvalid_pattern.search(line):