1 files changed, 26 insertions, 9 deletions

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)