From e707ea9bffe22e6b0b5ace503c11d4f551aa16a2 Mon Sep 17 00:00:00 2001
From: Cameron Dale <camrdale@gmail.com>
Date: Fri, 29 Feb 2008 13:42:28 -0800
Subject: [PATCH] Document the apt_dht_conf module.

---
 apt_dht/apt_dht_conf.py | 30 ++++++++++++++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)

diff --git a/apt_dht/apt_dht_conf.py b/apt_dht/apt_dht_conf.py
index 06709c3..0724172 100644
--- a/apt_dht/apt_dht_conf.py
+++ b/apt_dht/apt_dht_conf.py
@@ -1,21 +1,36 @@
 
+"""Loading of configuration files and parameters.
+
+@type version: L{twisted.python.versions.Version}
+@var version: the version of this program
+@type DEFAULT_CONFIG_FILES: C{list} of C{string}
+@var DEFAULT_CONFIG_FILES: the default config files to load (in order)
+@var DEFAULTS: the default config parameter values for the main program
+@var DHT_DEFAULTS: the default config parameter values for the default DHT
+
+"""
+
 import os, sys
 from ConfigParser import SafeConfigParser
 
 from twisted.python import log, versions
 
 class ConfigError(Exception):
+    """Errors that occur in the loading of configuration variables."""
     def __init__(self, message):
         self.message = message
     def __str__(self):
         return repr(self.message)
 
 version = versions.Version('apt-dht', 0, 0, 0)
+
+# Set the home parameter
 home = os.path.expandvars('${HOME}')
 if home == '${HOME}' or not os.path.isdir(home):
     home = os.path.expanduser('~')
     if not os.path.isdir(home):
         home = os.path.abspath(os.path.dirname(sys.argv[0]))
+
 DEFAULT_CONFIG_FILES=['/etc/apt-dht/apt-dht.conf',
                       home + '/.apt-dht/apt-dht.conf']
 
@@ -106,9 +121,12 @@ DHT_DEFAULTS = {
 }
 
 class AptDHTConfigParser(SafeConfigParser):
+    """Adds 'gettime' and 'getstringlist' to ConfigParser objects.
+    
+    @param time_multipliers: the 'gettime' suffixes and the multipliers needed
+        to convert them to seconds
     """
-    Adds 'gettime' to ConfigParser to interpret the suffixes.
-    """
+    
     time_multipliers={
         's': 1,    #seconds
         'm': 60,   #minutes
@@ -117,6 +135,7 @@ class AptDHTConfigParser(SafeConfigParser):
         }
 
     def gettime(self, section, option):
+        """Read the config parameter as a time value."""
         mult = 1
         value = self.get(section, option)
         if len(value) == 0:
@@ -126,13 +145,20 @@ class AptDHTConfigParser(SafeConfigParser):
             mult = self.time_multipliers[suffix]
             value = value[:-1]
         return int(value)*mult
+    
     def getstring(self, section, option):
+        """Read the config parameter as a string."""
         return self.get(section,option)
+    
     def getstringlist(self, section, option):
+        """Read the multi-line config parameter as a list of strings."""
         return self.get(section,option).split()
+
     def optionxform(self, option):
+        """Use all uppercase in the config parameters names."""
         return option.upper()
 
+# Initialize the default config parameters
 config = AptDHTConfigParser(DEFAULTS)
 config.add_section(config.get('DEFAULT', 'DHT'))
 for k in DHT_DEFAULTS:
-- 
2.30.2