Clarify the copy-existing-baselines-internal command.

third_party/WebKit/Tools/Scripts/webkitpy/tool/commands/rebaseline.py

 # Copyright (c) 2010 Google Inc. All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are
 # met:
 #
 #     * Redistributions of source code must retain the above copyright
 # notice, this list of conditions and the following disclaimer.
 #     * Redistributions in binary form must reproduce the above
 # copyright notice, this list of conditions and the following disclaimer
@@ skipping 130 matching lines @@
     def __init__(self):
         super(CopyExistingBaselinesInternal, self).__init__(options=[
             self.results_directory_option,
             self.suffixes_option,
             self.builder_option,
             self.test_option,
         ])
 
     @memoized
     def _immediate_predecessors_in_fallback(self, path_to_rebaseline):
+        """Returns the predecessor directories in the baseline fall-back graph.
+
+        The platform-specific fall-back baseline directories form a tree; the
+        "immediate predecessors" are the children nodes For example, if the
+        baseline fall-back graph includes:
+            "mac10.9" -> "mac10.10/"
+            "mac10.10/" -> "mac/"
+            "retina/" -> "mac/"
+        Then, the "immediate predecessors" are:
+            "mac/": ["mac10.10/", "retina/"]
+            "mac10.10/": ["mac10.9/"]
+            "mac10.9/", "retina/": []
+        """
         port_names = self._tool.port_factory.all_port_names()
         immediate_predecessors = []
         for port_name in port_names:
             port = self._tool.port_factory.get(port_name)
             if not port.buildbot_archives_baselines():
                 continue
             baseline_search_path = port.baseline_search_path()
             try:
                 index = baseline_search_path.index(path_to_rebaseline)
                 if index:
                     immediate_predecessors.append(self._tool.filesystem.basename(baseline_search_path[index - 1]))
             except ValueError:
                 # baseline_search_path.index() throws a ValueError if the item isn't in the list.
                 pass
         return immediate_predecessors
 
     def _port_for_primary_baseline(self, baseline):
+        """Returns a Port object for the given baseline directory base name."""
         for port in [self._tool.port_factory.get(port_name) for port_name in self._tool.port_factory.all_port_names()]:
             if self._tool.filesystem.basename(port.baseline_version_dir()) == baseline:
                 return port
         raise Exception("Failed to find port for primary baseline %s." % baseline)
 
     def _copy_existing_baseline(self, builder_name, test_name, suffix):
+        """Copies the baseline for the given builder to all "predecessor" directories."""
         baseline_directory = self._baseline_directory(builder_name)
         ports = [self._port_for_primary_baseline(baseline)
                  for baseline in self._immediate_predecessors_in_fallback(baseline_directory)]
 
         old_baselines = []
         new_baselines = []
 
         # Need to gather all the baseline paths before modifying the filesystem since
         # the modifications can affect the results of port.expected_filename.
         for port in ports:
@@ skipping 533 matching lines @@
             for test in args:
                 if test not in test_prefix_list:
                     test_prefix_list[test] = {}
                 build = Build(builder)
                 test_prefix_list[test][build] = suffixes_to_update
 
         if options.verbose:
             _log.debug("rebaseline-json: " + str(test_prefix_list))
 
         self.rebaseline(options, test_prefix_list)