Refining the documentations.

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

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

5 files changed, 33 insertions, 26 deletions

diff --git a/bestflags/flags.py b/bestflags/flags.py
index 37c21226..7e7ea674 100644
--- a/bestflags/flags.py
+++ b/bestflags/flags.py
@@ -93,18 +93,19 @@ class Flag(object):
   def __init__(self, spec, value=-1):
     self._spec = spec
 
-    # If the value is not specified, a random value is used.
+    # If the value is not specified, generate a random value to use.
     if value == -1:
-      result = rx.search(spec)
-
-      # The value of a boolean flag is 0.
+      # If creating a boolean flag, the value will be 0.
       value = 0
 
+      # Parse the spec's expression for the flag value's numeric range.
+      numeric_flag_match = Search(spec)
+
       # If this is a numeric flag, a value is chosen within start and end, start
       # inclusive and end exclusive.
-      if result:
-        start = int(result.group('start'))
-        end = int(result.group('end'))
+      if numeric_flag_match:
+        start = int(numeric_flag_match.group('start'))
+        end = int(numeric_flag_match.group('end'))
 
         assert start < end
         value = random.randint(start, end)
diff --git a/bestflags/flags_test.py b/bestflags/flags_test.py
index 3c424ff6..8ab0a9a5 100644
--- a/bestflags/flags_test.py
+++ b/bestflags/flags_test.py
@@ -2,7 +2,7 @@
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
-"""Flag unittest.
+"""Unit tests for the classes in module 'flags'.
 
 Part of the Chrome build flags optimization.
 """
@@ -46,7 +46,7 @@ class FlagTest(unittest.TestCase):
       assert start <= value and value < end
 
   def testEqual(self):
-    """Test the equal method of the flag.
+    """Test the equal operator (==) of the flag.
 
     Two flags are equal if and only if their spec and value are equal.
     """
@@ -59,11 +59,10 @@ class FlagTest(unittest.TestCase):
 
     # Two tasks having different flag set should be different.
     for test in tests:
-      flag0 = Flag(str(test), test)
+      flag = Flag(str(test), test)
       other_flag_sets = [other for other in tests if test != other]
-      for test1 in other_flag_sets:
-        flag1 = Flag(str(test1), test1)
-        assert flag0 != flag1
+      for other_test in other_flag_sets:
+        assert flag != Flag(str(other_test), other_test)
 
   def testFormattedForUse(self):
     """Test the FormattedForUse method of the flag.
@@ -153,7 +152,7 @@ class FlagSetTest(unittest.TestCase):
     """
 
     true_tests = range(NUM_TESTS)
-    false_tests = range(NUM_TESTS, NUM_TESTS + NUM_TESTS)
+    false_tests = range(NUM_TESTS, NUM_TESTS * 2)
 
     specs = [str(spec) for spec in true_tests]
 
diff --git a/bestflags/flags_util.py b/bestflags/flags_util.py
index 23decafd..ae19a60b 100644
--- a/bestflags/flags_util.py
+++ b/bestflags/flags_util.py
@@ -15,7 +15,10 @@ from flags import Flag
 
 
 def ClimbNext(flags_dict, climb_spec):
-  """Get the flags who are different from flags_dict by climb_spec.
+  """Get the flags that are different from |flags_dict| by |climb_spec|.
+
+  Given a set of flags, |flags_dict|, return a new set of flags that are
+  adjacent along the flag spec |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
@@ -31,7 +34,7 @@ def ClimbNext(flags_dict, climb_spec):
       fillable value. An example of a spec is "foo[0-9]".
 
   Returns:
-    Dictionaries of neighbor flags.
+    List of dictionaries of neighbor flags.
   """
 
   # This method searches for a pattern [start-end] in the spec. If the spec
diff --git a/bestflags/genetic_algorithm.py b/bestflags/genetic_algorithm.py
index be9e8970..15ad1f74 100644
--- a/bestflags/genetic_algorithm.py
+++ b/bestflags/genetic_algorithm.py
@@ -61,18 +61,18 @@ def RandomMutate(specs, flag_set, mutation_rate):
       continue
 
     # If the flag is already in the flag set, it is mutated.
-    result = flags.Search(spec)
+    numeric_flag_match = flags.Search(spec)
 
     # The value of a numeric flag will be changed, and a boolean flag will be
     # dropped.
-    if not result:
+    if not numeric_flag_match:
       continue
 
     value = flag_set[spec].GetValue()
 
     # Randomly select a nearby value of the current value of the flag.
     rand_arr = [value]
-    if value + 1 < int(result.group('end')):
+    if value + 1 < int(numeric_flag_match.group('end')):
       rand_arr.append(value + 1)
 
     rand_arr.append(value - 1)
@@ -80,7 +80,7 @@ def RandomMutate(specs, flag_set, mutation_rate):
 
     # If the value is smaller than the start of the spec, this flag will be
     # dropped.
-    if value != int(result.group('start')) - 1:
+    if value != int(numeric_flag_match.group('start')) - 1:
       results_flags.append(Flag(spec, value))
 
   return GATask(FlagSet(results_flags))
diff --git a/bestflags/testing_batch.py b/bestflags/testing_batch.py
index ad1ab4b7..f44c4f66 100644
--- a/bestflags/testing_batch.py
+++ b/bestflags/testing_batch.py
@@ -55,11 +55,11 @@ def _GenerateRandomRasks(specs):
   flag_set = []
 
   for spec in specs:
-    result = flags.Search(spec)
-    if result:
+    numeric_flag_match = flags.Search(spec)
+    if numeric_flag_match:
       # Numeric flags.
-      start = int(result.group('start'))
-      end = int(result.group('end'))
+      start = int(numeric_flag_match.group('start'))
+      end = int(numeric_flag_match.group('end'))
 
       value = random.randint(start - 1, end - 1)
       if value != start - 1:
@@ -89,8 +89,12 @@ def _GenerateAllFlagsTasks(specs):
   flag_set = []
 
   for spec in specs:
-    result = flags.Search(spec)
-    value = (int(result.group('end')) - 1) if result else -1
+    numeric_flag_match = flags.Search(spec)
+
+    if numeric_flag_match:
+      value = (int(numeric_flag_match.group('end')) - 1)
+    else:
+      value = -1
     flag_set.append(Flag(spec, value))
 
   return set([Task(FlagSet(flag_set))])