[PATCH] Improve CustomConfig documentation

[Sebastian Spaeth]

Improve documentation about what CustomConfigHelperMixin does,
it was not very clear without a close look to the code before.

Signed-off-by: Sebastian Spaeth <Sebastian at SSpaeth.de>
---
This is the next patch in my cleanup series that lingers on my
harddisk since Nov 23. it adds some documentation on code and
classes that I found a bit puzzling to understand when I first
browsed through them.

 offlineimap/CustomConfig.py |   28 +++++++++++++++++++++-------
 1 files changed, 21 insertions(+), 7 deletions(-)

diff --git a/offlineimap/CustomConfig.py b/offlineimap/CustomConfig.py
index 07be0f6..0c10271 100644
--- a/offlineimap/CustomConfig.py
+++ b/offlineimap/CustomConfig.py
@@ -71,18 +71,33 @@ class CustomConfigParser(ConfigParser):
                 if x.startswith(key)]
 
 def CustomConfigDefault():
-    """Just a sample constant that won't occur anywhere else to use for the
-    default."""
+    """Just a constant that won't occur anywhere else.
+
+    This allows us to differentiate if the user has passed in any
+    default value to the getconf* functions in ConfigHelperMixin
+    derived classes."""
     pass
 
 class ConfigHelperMixin:
+    """Allow comfortable retrieving of config values pertaining to a section.
+
+    If a class inherits from this cls:`ConfigHelperMixin`, it needs
+    to provide 2 functions: meth:`getconfig` (returning a
+    ConfigParser object) and meth:`getsection` (returning a string
+    which represents the section to look up). All calls to getconf*
+    will then return the configuration values for the ConfigParser
+    object in the specific section."""
+
     def _confighelper_runner(self, option, default, defaultfunc, mainfunc):
-        if default != CustomConfigDefault:
-            return apply(defaultfunc, [self.getsection(), option, default])
-        else:
+        """Return config value for getsection()"""
+        if default == CustomConfigDefault:
             return apply(mainfunc, [self.getsection(), option])
+        else:
+            return apply(defaultfunc, [self.getsection(), option, default])
 
-    def getconf(self, option, default = CustomConfigDefault):
+
+    def getconf(self, option,
+                default = CustomConfigDefault):
         return self._confighelper_runner(option, default,
                                          self.getconfig().getdefault,
                                          self.getconfig().get)
@@ -101,4 +116,3 @@ class ConfigHelperMixin:
         return self._confighelper_runner(option, default,
                                          self.getconfig().getdefaultfloat,
                                          self.getconfig().getfloat)
-    
-- 
1.7.1