Add and clean up docstrings in webkitpy/w3c.

third_party/WebKit/Tools/Scripts/webkitpy/w3c/test_importer.py

 # Copyright (C) 2013 Adobe Systems Incorporated. All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions
 # are met:
 #
 # 1. Redistributions of source code must retain the above
 #    copyright notice, this list of conditions and the following
 #    disclaimer.
 # 2. Redistributions in binary form must reproduce the above
 #    copyright notice, this list of conditions and the following
 #    disclaimer in the documentation and/or other materials
 #    provided with the distribution.
 #
 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER "AS IS" AND ANY
 # EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 # PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE
 # LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
 # OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 # PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 # PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
 # TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
 # THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 # SUCH DAMAGE.
 
 """
- This script imports a directory of W3C tests into Blink.
+This script imports a directory of W3C tests into Blink.
 
- This script will import the tests into WebKit following these rules:
+This script takes a source repository directory, which it searches for files,
+then converts and copies files over to a destination directory.
 
-    - By default, all tests are imported under LayoutTests/w3c/[repo-name].
+Rules for importing:
 
-    - By default, only reftests and jstest are imported. This can be overridden
-      with a -a or --all argument
+ * By default, only reference tests and JS tests are imported, (because pixel
+   tests take longer to run). This can be overridden with the --all flag.
 
-    - Also by default, if test files by the same name already exist in the
-      destination directory, they are overwritten with the idea that running
-      this script would refresh files periodically.  This can also be
-      overridden by a -n or --no-overwrite flag
+ * By default, if test files by the same name already exist in the destination
+   directory, they are overwritten. This is because this script is used to
+   refresh files periodically. This can be overridden with the --no-overwrite flag.
 
-    - All files are converted to work in Blink:
-         1. All CSS properties requiring the -webkit- vendor prefix are prefixed
-            (the list of what needs prefixes is read from Source/core/css/CSSProperties.in).
-         2. Each reftest has its own copy of its reference file following
-            the naming conventions new-run-webkit-tests expects.
-         3. If a reference files lives outside the directory of the test that
-            uses it, it is checked for paths to support files as it will be
-            imported into a different relative position to the test file
-            (in the same directory).
-         4. Any tags with the class "instructions" have style="display:none" added
-            to them. Some w3c tests contain instructions to manual testers which we
-            want to strip out (the test result parser only recognizes pure testharness.js
-            output and not those instructions).
+ * All files are converted to work in Blink:
+     1. All CSS properties requiring the -webkit- vendor prefix are prefixed
+        (the list of what needs prefixes is read from Source/core/css/CSSProperties.in).
+     2. Each reftest has its own copy of its reference file following
+        the naming conventions new-run-webkit-tests expects.
+     3. If a reference files lives outside the directory of the test that
+        uses it, it is checked for paths to support files as it will be
+        imported into a different relative position to the test file
+        (in the same directory).
+     4. Any tags with the class "instructions" have style="display:none" added
+        to them. Some w3c tests contain instructions to manual testers which we
+        want to strip out (the test result parser only recognizes pure testharness.js
+        output and not those instructions).
 
-     - Upon completion, script outputs the total number tests imported, broken
-       down by test type
+ * Upon completion, script outputs the total number tests imported,
+   broken down by test type.
 
-     - Also upon completion, if we are not importing the files in place, each
-       directory where files are imported will have a w3c-import.log file written with
-       a timestamp, the list of CSS properties used that require prefixes, the list
-       of imported files, and guidance for future test modification and maintenance.
-       On subsequent imports, this file is read to determine if files have been
-       removed in the newer changesets. The script removes these files accordingly.
+ * Also upon completion, if we are not importing the files in place, each
+   directory where files are imported will have a w3c-import.log file written with
+   a timestamp, the list of CSS properties used that require prefixes, the list
+   of imported files, and guidance for future test modification and maintenance.
+   On subsequent imports, this file is read to determine if files have been
+   removed in the newer changesets. The script removes these files accordingly.
 """
 
 import logging
 import mimetypes
 import optparse
 import os
 import sys
 
 from webkitpy.common.host import Host
 from webkitpy.common.webkit_finder import WebKitFinder
@@ skipping 91 matching lines @@
         self.dir_above_repo = self.filesystem.dirname(self.top_of_repo)
 
         self.import_list = []
 
     def do_import(self):
         _log.info("Importing %s into %s", self.dir_to_import, self.destination_directory)
         self.find_importable_tests(self.dir_to_import)
         self.import_tests()
 
     def find_importable_tests(self, directory):
+        """Walks through the source directory to find what tests should be imported.
+
+        This function sets self.import_list, which contains information about how many
+        tests are being imported, and their source and destination paths.
+        """
         paths_to_skip = self.find_paths_to_skip()
 
         for root, dirs, files in self.filesystem.walk(directory):
             cur_dir = root.replace(self.dir_above_repo + '/', '') + '/'
             _log.info('  scanning ' + cur_dir + '...')
             total_tests = 0
             reftests = 0
             jstests = 0
 
             # Files in 'tools' are not for browser testing (e.g., a script for generating test files).
@@ skipping 111 matching lines @@
         expectation_lines = parser.parse(w3c_import_expectations_path, w3c_import_expectations)
         for line in expectation_lines:
             if 'SKIP' in line.expectations:
                 if line.specifiers:
                     _log.warning("W3CImportExpectations:%s should not have any specifiers" % line.line_numbers)
                     continue
                 paths_to_skip.add(line.name)
         return paths_to_skip
 
     def import_tests(self):
+        """Reads |self.import_list|, and converts and copies files to their destination."""
         total_imported_tests = 0
         total_imported_reftests = 0
         total_imported_jstests = 0
         total_prefixed_properties = {}
 
         for dir_to_copy in self.import_list:
             total_imported_tests += dir_to_copy['total_tests']
             total_imported_reftests += dir_to_copy['reftests']
             total_imported_jstests += dir_to_copy['jstests']
 
@@ skipping 37 matching lines @@
 
                 relpath = self.filesystem.relpath(new_filepath, self.layout_tests_dir)
                 if not self.options.overwrite and self.filesystem.exists(new_filepath):
                     _log.info('  skipping %s' % relpath)
                 else:
                     # FIXME: Maybe doing a file diff is in order here for existing files?
                     # In other words, there's no sense in overwriting identical files, but
                     # there's no harm in copying the identical thing.
                     _log.info('  %s' % relpath)
 
-                # Only html, xml, or css should be converted
-                # FIXME: Eventually, so should js when support is added for this type of conversion
+                # Only HTML, XML, or CSS should be converted.
+                # FIXME: Eventually, so should JS when support is added for this type of conversion.
                 mimetype = mimetypes.guess_type(orig_filepath)
                 if 'html' in str(mimetype[0]) or 'xml' in str(mimetype[0]) or 'css' in str(mimetype[0]):
                     converted_file = convert_for_webkit(new_path, filename=orig_filepath,
                                                         reference_support_info=reference_support_info)
 
                     if not converted_file:
                         if not self.import_in_place and not self.options.dry_run:
                             self.filesystem.copyfile(orig_filepath, new_filepath)  # The file was unmodified.
                     else:
                         for prefixed_property in converted_file[0]:
@@ skipping 28 matching lines @@
     def path_too_long(self, source_path):
         """Checks whether a source path is too long to import.
 
         Args:
           Absolute path of file to be imported.
         """
         path_from_repo_base = os.path.relpath(source_path, self.top_of_repo)
         return len(path_from_repo_base) > MAX_PATH_LENGTH
 
     def setup_destination_directory(self):
-        """ Creates a destination directory that mirrors that of the source directory """
+        """Creates a destination directory that mirrors that of the source directory."""
 
         new_subpath = self.dir_to_import[len(self.top_of_repo):]
 
         destination_directory = self.filesystem.join(self.destination_directory, new_subpath)
 
         if not self.filesystem.exists(destination_directory):
             self.filesystem.maybe_make_directory(destination_directory)
 
         _log.info('Tests will be imported into: %s', destination_directory)