From 50ebdd7f2cdbfeb552168ab3346a7a87adc69be5 Mon Sep 17 00:00:00 2001
From: Andrew Brown <brownan@gmail.com>
Date: Sun, 5 Feb 2012 00:20:58 -0500
Subject: [PATCH] clarified some comments and conformed some function names

---
 overviewer_core/configParser.py       |  2 +-
 overviewer_core/settingsDefinition.py |  8 ++++----
 overviewer_core/settingsValidators.py | 21 +++++++++++++--------
 3 files changed, 18 insertions(+), 13 deletions(-)

diff --git a/overviewer_core/configParser.py b/overviewer_core/configParser.py
index 5cc2b14..e804d54 100644
--- a/overviewer_core/configParser.py
+++ b/overviewer_core/configParser.py
@@ -67,7 +67,7 @@ class MultiWorldParser(object):
         """Validate and return the configuration"""
         # Okay, this is okay, isn't it? We're going to create the validation
         # routine right here, right now. I hope this works!
-        validator = settingsValidators.make_configdictvalidator(self._settings)
+        validator = settingsValidators.make_configDictValidator(self._settings)
         # Woah. What just happened? No. WAIT, WHAT ARE YOU...
         validated_config = validator(self._config_state)
         # WHAT HAVE YOU DONE?
diff --git a/overviewer_core/settingsDefinition.py b/overviewer_core/settingsDefinition.py
index e267be6..1bbe2c3 100644
--- a/overviewer_core/settingsDefinition.py
+++ b/overviewer_core/settingsDefinition.py
@@ -31,8 +31,8 @@
 #   appear in the resulting parsed options.
 
 # The signature for validator callables is validator(value_given). Remember
-# that the default is passed in as value_given in the event that required is
-# False and default is not None.
+# that the default is passed in as value_given if the user did not provide a
+# value.
 
 # This file doesn't specify the format or even the type of the setting values,
 # it is up to the validators to ensure the values passed in are the right type,
@@ -61,7 +61,7 @@ __all__ = ['render', 'world', 'outputdir']
 
 # config file.
 render = Setting(required=True, default={},
-        validator=dictValidator(validateStr, make_configdictvalidator(
+        validator=make_dictValidator(validateStr, make_configDictValidator(
         {
             "worldname": Setting(required=True, validator=validateStr, default=None),
             "dimension": Setting(required=True, validator=validateDimension, default="default"),
@@ -83,7 +83,7 @@ render = Setting(required=True, default={},
         )))
 
 # The world dict, mapping world names to world paths
-world = Setting(required=True, validator=dictValidator(validateStr, validateWorldPath), default={})
+world = Setting(required=True, validator=make_dictValidator(validateStr, validateWorldPath), default={})
 
 outputdir = Setting(required=True, validator=validateOutputDir, default=None)
 
diff --git a/overviewer_core/settingsValidators.py b/overviewer_core/settingsValidators.py
index 223a7a5..126c634 100644
--- a/overviewer_core/settingsValidators.py
+++ b/overviewer_core/settingsValidators.py
@@ -133,9 +133,12 @@ def validateOutputDir(d):
         raise ValidationException("You must specify a valid output directory")
     return os.path.abspath(d)
 
-def dictValidator(keyvalidator, valuevalidator):
-    """Compose a dict validator by validating each key/value combination with
-    the given key validator and value validator
+def make_dictValidator(keyvalidator, valuevalidator):
+    """Compose and return a dict validator -- a validator that validates each
+    key and value in a dictionary.
+
+    The arguments are the validator function to use for the keys, and the
+    validator function to use for the values.
     
     """
     def v(d):
@@ -145,13 +148,15 @@ def dictValidator(keyvalidator, valuevalidator):
         return newd
     return v
 
-def make_configdictvalidator(config):
+def make_configDictValidator(config):
     """Okay, stay with me here, this may get confusing. This function returns a
     validator that validates a "configdict". This is a term I just made up to
-    refer to a dict where keys are strings and values are something. The
-    argument to /this/ function is a dictionary mapping those key names to
-    Setting objects. When the validator validates, it calls all the appropriate
-    validators to validate each item in the configdict.
+    refer to a dict that holds config information: keys are strings and values
+    are whatever that config value is. The argument to /this/ function is a
+    dictionary defining the valid keys for the configdict. It therefore maps
+    those key names to Setting objects. When the returned validator function
+    validates, it calls all the appropriate validators for each configdict
+    setting
 
     I hope that makes sense.