Add more examples for better documentation.

BUG=None
TEST=unit testings for the pipeline stage, pipeline workers, generation,
steering, task, flag and hill climbing.

Change-Id: I1f8f361388d3c3171a7135d1d0ef38ee5f695829
Reviewed-on: https://gerrit-int.chromium.org/42584
Reviewed-by: Luis Lozano <llozano@chromium.org>
Commit-Queue: Yuheng Long <yuhenglong@google.com>
Tested-by: Yuheng Long <yuhenglong@google.com>

8 files changed, 57 insertions, 24 deletions

diff --git a/bestflags/flags.py b/bestflags/flags.py
index a89f6301..37c21226 100644
--- a/bestflags/flags.py
+++ b/bestflags/flags.py
@@ -44,6 +44,11 @@ def Search(spec):
   return rx.search(spec)
 
 
+class NoSuchFileError(Exception):
+  """Define an Exception class for user providing invalid input file."""
+  pass
+
+
 def ReadConf(file_name):
   """Parse the configuration file.
 
@@ -54,24 +59,35 @@ def ReadConf(file_name):
 
   Returns:
     A list of specs in the configuration file.
+
+  Raises:
+    NoSuchFileError: The caller should provide a valid configuration file.
   """
 
   with open(file_name, 'r') as input_file:
     lines = input_file.readlines()
 
     return sorted([line.strip() for line in lines if line.strip()])
-  return []
+
+  raise NoSuchFileError()
 
 
 class Flag(object):
   """A class representing a particular command line flag argument.
 
   The Flag consists of two parts: The spec and the value.
-  The spec is a definition in the little language, a string of the form
-  [<start>-<end>] where start and end is an positive integer for a fillable
-  value.
+  The spec is a definition of the following form: a string with escaped
+  sequences of the form [<start>-<end>] where start and end is an positive
+  integer for a fillable value.
 
   An example of a spec is "foo[0-9]".
+  There are two kinds of flags, boolean flag and numeric flags. Boolean flags
+  can either be turned on or off, which numeric flags can have different
+  positive integer values. For example, -finline-limit=[1-1000] is a numeric
+  flag and -ftree-vectorize is a boolean flag.
+
+  A (boolean/numeric) flag is not turned on if it is not selected in the
+  FlagSet.
   """
 
   def __init__(self, spec, value=-1):
diff --git a/bestflags/flags_util.py b/bestflags/flags_util.py
index 01cc8d66..23decafd 100644
--- a/bestflags/flags_util.py
+++ b/bestflags/flags_util.py
@@ -17,24 +17,37 @@ from flags import Flag
 def ClimbNext(flags_dict, climb_spec):
   """Get the flags who are different from flags_dict by climb_spec.
 
+  An example flags_dict is {foo=[1-9]:foo=5, bar=[1-5]:bar=2} and climb_spec is
+  bar=[1-5]. This method changes the flag that contains the spec bar=[1-5]. The
+  results are its neighbors dictionaries, i.e., {foo=[1-9]:foo=5,
+  bar=[1-5]:bar=1} and {foo=[1-9]:foo=5, bar=[1-5]:bar=3}.
+
   Args:
     flags_dict: The dictionary containing the original flags whose neighbors are
       to be explored.
-    climb_spec: The spec in the flags_dict is to be changed.
+    climb_spec: The spec in the flags_dict is to be changed. The spec is a
+      definition in the little language, a string with escaped sequences of the
+      form [<start>-<end>] where start and end is an positive integer for a
+      fillable value. An example of a spec is "foo[0-9]".
 
   Returns:
-    A dictionary of neighbor flags.
+    Dictionaries of neighbor flags.
   """
 
-  result = flags.Search(climb_spec)
+  # This method searches for a pattern [start-end] in the spec. If the spec
+  # contains this pattern, it is a numeric flag. Otherwise it is a boolean flag.
+  # For example, -finline-limit=[1-1000] is a numeric flag and -falign-jumps is
+  # a boolean flag.
+  numeric_flag_match = flags.Search(climb_spec)
 
   # If the flags do not contain the spec.
   if climb_spec not in flags_dict:
     results = flags_dict.copy()
 
-    if result:
+    if numeric_flag_match:
       # Numeric flags.
-      results[climb_spec] = Flag(climb_spec, int(result.group('start')))
+      results[climb_spec] = Flag(climb_spec,
+                                 int(numeric_flag_match.group('start')))
     else:
       # Boolean flags.
       results[climb_spec] = Flag(climb_spec)
@@ -42,9 +55,12 @@ def ClimbNext(flags_dict, climb_spec):
     return [results]
 
   # The flags contain the spec.
-  if not result:
+  if not numeric_flag_match:
     # Boolean flags.
     results = flags_dict.copy()
+
+    # Turn off the flag. A flag is turned off if it is not presented in the
+    # flags_dict.
     del results[climb_spec]
     return [results]
 
@@ -55,21 +71,22 @@ def ClimbNext(flags_dict, climb_spec):
   value = flag.GetValue()
   results = []
 
-  if value + 1 < int(result.group('end')):
+  if value + 1 < int(numeric_flag_match.group('end')):
     # If the value is not the end value, explore the value that is 1 larger than
     # the current value.
     neighbor = flags_dict.copy()
     neighbor[climb_spec] = Flag(climb_spec, value + 1)
     results.append(neighbor)
 
-  if value > int(result.group('start')):
+  if value > int(numeric_flag_match.group('start')):
     # If the value is not the start value, explore the value that is 1 lesser
     # than the current value.
     neighbor = flags_dict.copy()
     neighbor[climb_spec] = Flag(climb_spec, value - 1)
     results.append(neighbor)
   else:
-    # Delete the value.
+    # Delete the value, i.e., turn off the flag. A flag is turned off if it is
+    # not presented in the flags_dict.
     neighbor = flags_dict.copy()
     del neighbor[climb_spec]
     results.append(neighbor)
diff --git a/bestflags/generation.py b/bestflags/generation.py
index 8e1358ad..6fe851a8 100644
--- a/bestflags/generation.py
+++ b/bestflags/generation.py
@@ -28,7 +28,7 @@ class Generation(object):
   """A generation of a framework run.
 
   The base class of generation. Concrete subclasses, e.g., GAGeneration should
-  override the Next and Improve method to implement algorithm specific
+  override the Next and Improved method to implement algorithm specific
   applications.
   """
 
@@ -111,7 +111,7 @@ class Generation(object):
 
     return True
 
-  def Improve(self):
+  def Improved(self):
     """True if this generation has improvement upon its parent generation.
 
     Raises:
diff --git a/bestflags/genetic_algorithm.py b/bestflags/genetic_algorithm.py
index 56b1dcc1..0e7de07f 100644
--- a/bestflags/genetic_algorithm.py
+++ b/bestflags/genetic_algorithm.py
@@ -200,7 +200,7 @@ class GAGeneration(Generation):
     Generation.__init__(self, tasks, parents)
     self._total_stucks = total_stucks
 
-  def Improve(self):
+  def Improved(self):
     """True if this generation has improvement upon its parent generation."""
 
     tasks = self.Pool()
@@ -216,7 +216,7 @@ class GAGeneration(Generation):
     best_current = sorted(tasks, key=lambda task: task.GetTestResult())[0]
 
     # At least one task has improvement.
-    if best_current.Improve(best_parent):
+    if best_current.Improved(best_parent):
       self._total_stucks = 0
       return True
 
diff --git a/bestflags/hill_climb_best_neighbor.py b/bestflags/hill_climb_best_neighbor.py
index 5bc3f7ed..aec420f9 100644
--- a/bestflags/hill_climb_best_neighbor.py
+++ b/bestflags/hill_climb_best_neighbor.py
@@ -41,7 +41,7 @@ class HillClimbingBestBranch(Generation):
     Generation.__init__(self, exe_pool, parents)
     self._specs = specs
 
-  def Improve(self):
+  def Improved(self):
     """True if this generation has improvement over its parent generation.
 
     Returns:
@@ -51,7 +51,7 @@ class HillClimbingBestBranch(Generation):
     # Find the best neighbor.
     best_task = None
     for task in self._exe_pool:
-      if not best_task or task.Improve(best_task):
+      if not best_task or task.Improved(best_task):
         best_task = task
 
     if not best_task:
@@ -63,7 +63,7 @@ class HillClimbingBestBranch(Generation):
       assert len(parents) == 1
       self._next_task = best_task
       # If the best neighbor improves upon the parent task.
-      return best_task.Improve(parents[0])
+      return best_task.Improved(parents[0])
 
     self._next_task = best_task
     return True
diff --git a/bestflags/steering.py b/bestflags/steering.py
index 2f889ca1..5cdf8aed 100644
--- a/bestflags/steering.py
+++ b/bestflags/steering.py
@@ -99,7 +99,7 @@ def Steering(cache, generations, input_queue, result_queue):
     # A generation may not generate the next generation, e.g., because a
     # fixpoint has been reached, there has not been any improvement for a few
     # generations or a local maxima is reached.
-    if not generation.Improve():
+    if not generation.Improved():
       continue
 
     for new_generation in generation.Next(cache):
diff --git a/bestflags/steering_test.py b/bestflags/steering_test.py
index b3ce686d..5063079c 100644
--- a/bestflags/steering_test.py
+++ b/bestflags/steering_test.py
@@ -53,7 +53,7 @@ class MockGeneration(Generation):
   def Next(self, _):
     return self._next_generations
 
-  def Improve(self):
+  def Improved(self):
     if self._next_generations:
       return True
     return False
diff --git a/bestflags/task.py b/bestflags/task.py
index 77901602..b20493fd 100644
--- a/bestflags/task.py
+++ b/bestflags/task.py
@@ -31,7 +31,7 @@ ERROR_STRING = 'error'
 # the build should attempt before giving up.
 BUILD_TRIES = 3
 
-# The maximum number of tries a build can have. Some tests may fail due to
+# The maximum number of tries a test can have. Some tests may fail due to
 # unexpected environment circumstance. This variable defines how many tries the
 # test should attempt before giving up.
 TEST_TRIES = 3
@@ -391,7 +391,7 @@ class Task(object):
       # Write out the result in the comma-separated format (CSV).
       out_file.write('%s,%s,%s\n' % test_result)
 
-  def Improve(self, other):
+  def Improved(self, other):
     """Compare the current task with another task.
 
     Args: