Make docstrings more consistent using format-webkitpy.

third_party/WebKit/Tools/Scripts/webkitpy/formatter/fix_docstrings.py

 # Copyright 2016 The Chromium Authors. All rights reserved.
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
 """A 2to3 fixer that reformats docstrings.
 
 This should transform docstrings to be closer to the conventions in pep-0257;
 see https://www.python.org/dev/peps/pep-0257/.
 """
 
 import re
 
 from lib2to3.fixer_base import BaseFix
 from lib2to3.pgen2 import token
+from lib2to3.pygram import python_symbols
 
 
 class FixDocstrings(BaseFix):
 
     explicit = True
     _accept_type = token.STRING
 
     def match(self, node):
-        return node.value.startswith('"""') and node.prev_sibling is None
+        """Returns True if the given node appears to be a docstring.
+
+        Docstrings should always have no previous siblings, and should be
+        direct children of simple_stmt.
+
+        Note: This may also match for some edge cases where there are
+        simple_stmt strings that aren't the first thing in a module, class
+        or function, and thus aren't considered docstrings; but changing these
+        strings should not change behavior.
+        """
+        # Pylint incorrectly warns that there's no member simple_stmt on python_symbols
+        # because the attribute is set dynamically.  pylint: disable=no-member
+        return (node.value.startswith('"""') and
+                node.prev_sibling is None and
+                node.parent.type == python_symbols.simple_stmt)

[qyearsley, 2016/09/04 19:42:46]

After running the formatter on the webkitpy codebase, I found a few cases where
the formatter was incorrectly applied, which were all of the form:

    some_function("""
    some string that's not a docstring
    """)

Unfortunately, I couldn't easily add a test for this that would fail with the
previous code (when the match function was not strict enough); it appears that
the way that the code is parsed in the sample inputs in
formatter/main_unittest.py is different than when it's parsing real Python
source code.

After changing the match function to only match when the parent node type is
simple_stmt, then it appears to work correctly for all code in webkitpy.

[Dirk Pranke, 2016/09/06 01:14:27]

Acknowledged.

 
     def transform(self, node, results):
         # First, strip whitespace at the beginning and end.
         node.value = re.sub(r'^"""\s+', '"""', node.value)
         node.value = re.sub(r'\s+"""$', '"""', node.value)
 
         # For multi-line docstrings, the closing quotes should go on their own line.
         if '\n' in node.value:
             indent = re.search(r'\n( *)\S', node.value).group(1)
             node.value = re.sub(r'"""$', '\n' + indent + '"""', node.value)
 
         node.changed()