Add and clean up docstrings in webkitpy/w3c.

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

 #!/usr/bin/env python
 
 # 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
@@ skipping 51 matching lines @@
                 # FIXME: Figure out what is triggering this and what to do about it.
                 _log.error("Trying to load %s, which is a directory", filename)
             doc = None
 
         if is_ref:
             self.ref_doc = doc
         else:
             self.test_doc = doc
 
     def analyze_test(self, test_contents=None, ref_contents=None):
-        """ Analyzes a file to determine if it's a test, what type of test, and what reference or support files it requires. Returns all of the test info """
+        """Analyzes a file to determine if it's a test, what type of test, and what reference or support files it requires.
 
+        Returns: A dict which can have the properties:
+            "test": test file name.
+            "reference": related reference test file name if this is a reference test.
+            "reference_support_info": extra information about the related reference test and any support files.
+            "jstest": A boolean, whether this is a JS test.
+            If the given contents are empty, then None is returned.
+        """
         test_info = None
 
         if test_contents is None and self.test_doc is None:
             return test_info
 
         if test_contents is not None:
             self.test_doc = Parser(test_contents)
 
         if ref_contents is not None:
             self.ref_doc = Parser(ref_contents)
@@ skipping 11 matching lines @@
             except KeyError as e:
                 # FIXME: Figure out what to do w/ invalid test files.
                 _log.error('%s has a reference link but is missing the "href"', self.filesystem)
                 return None
 
             if self.ref_doc is None:
                 self.load_file(ref_file, True)
 
             test_info = {'test': self.filename, 'reference': ref_file}
 
-            # If the ref file does not live in the same directory as the test file, check it for support files
+            # If the ref file does not live in the same directory as the test file, check it for support files.
             test_info['reference_support_info'] = {}
             if self.filesystem.dirname(ref_file) != self.filesystem.dirname(self.filename):
                 reference_support_files = self.support_files(self.ref_doc)
                 if len(reference_support_files) > 0:
                     reference_relpath = self.filesystem.relpath(self.filesystem.dirname(
                         self.filename), self.filesystem.dirname(ref_file)) + self.filesystem.sep
                     test_info['reference_support_info'] = {'reference_relpath': reference_relpath, 'files': reference_support_files}
 
         elif self.is_jstest():
             test_info = {'test': self.filename, 'jstest': True}
         elif self.options['all'] is True and not('-ref' in self.filename) and not('reference' in self.filename):
             test_info = {'test': self.filename}
 
         return test_info
 
     def reference_links_of_type(self, reftest_type):
         return self.test_doc.findAll(rel=reftest_type)
 
     def is_jstest(self):
         """Returns whether the file appears to be a jstest, by searching for usage of W3C-style testharness paths."""
         return bool(self.test_doc.find(src=re.compile('[\'\"/]?/resources/testharness')))
 
     def support_files(self, doc):
-        """ Searches the file for all paths specified in url()'s or src attributes."""
+        """Searches the file for all paths specified in url()s or src attributes."""
         support_files = []
 
         if doc is None:
             return support_files
 
         elements_with_src_attributes = doc.findAll(src=re.compile('.*'))
         elements_with_href_attributes = doc.findAll(href=re.compile('.*'))
 
         url_pattern = re.compile('url\(.*\)')
         urls = []
         for url in doc.findAll(text=url_pattern):
             url = re.search(url_pattern, url)
             url = re.sub('url\([\'\"]?', '', url.group(0))
             url = re.sub('[\'\"]?\)', '', url)
             urls.append(url)
 
         src_paths = [src_tag['src'] for src_tag in elements_with_src_attributes]
         href_paths = [href_tag['href'] for href_tag in elements_with_href_attributes]
 
         paths = src_paths + href_paths + urls
         for path in paths:
             if not(path.startswith('http:')) and not(path.startswith('mailto:')):
                 uri_scheme_pattern = re.compile(r"[A-Za-z][A-Za-z+.-]*:")
                 if not uri_scheme_pattern.match(path):
                     support_files.append(path)
 
         return support_files