[minion-cvs] Documentation fixes; generic xreadlines wrapper

[nickm@xxxxxxxx (Nick Mathewson)]

Update of /home/minion/cvsroot/src/minion/lib/mixminion
In directory moria:/tmp/cvs-serv27082

Modified Files:
	Common.py 
Log Message:
Documentation fixes; generic xreadlines wrapper

Index: Common.py
===================================================================
RCS file: /home/minion/cvsroot/src/minion/lib/mixminion/Common.py,v
retrieving revision 1.145
retrieving revision 1.146
diff -u -d -r1.145 -r1.146
--- Common.py	3 May 2005 03:30:07 -0000	1.145
+++ Common.py	4 Jun 2005 13:52:14 -0000	1.146
@@ -12,8 +12,8 @@
             'createPrivateDir', 'disp64',
             'encodeBase64', 'englishSequence', 'floorDiv', 'formatBase64',
             'formatDate', 'formatFnameDate', 'formatFnameTime', 'formatTime',
-            'installSIGCHLDHandler', 'isSMTPMailbox', 'openUnique',
-            'parseFnameDate',
+            'installSIGCHLDHandler', 'isSMTPMailbox', 'iterFileLines',
+            'openUnique', 'parseFnameDate',
             'previousMidnight', 'readFile', 'readPickled',
             'readPossiblyGzippedFile', 'secureDelete', 'stringContains',
             'succeedingMidnight', 'tryUnlink', 'unarmorText',
@@ -51,6 +51,12 @@
 except ImportError:
     pwd = grp = None
 
+try:
+    file.__iter__
+    xreadlines = None
+except (KeyError, AttributeError), _:
+    import xreadlines
+
 from types import StringType
 
 class MixError(Exception):
@@ -337,8 +343,6 @@
 
 #----------------------------------------------------------------------
 
-#----------------------------------------------------------------------
-
 # A set of directories we've issued warnings about -- we won't check
 # them again.
 _WARNED_DIRECTORIES = {}
@@ -509,7 +513,6 @@
 #----------------------------------------------------------------------
 # File helpers
 
-
 # On windows, rename(f1,f2) fails if f2 already exists.  These wrappers
 # handle replacing files.
 if sys.platform == 'win32':
@@ -564,7 +567,10 @@
             LOG.error("Atomic file not closed/discarded: %s",self.tmpname)
 
 def iterFileLines(f):
-    #XXXXXX DOCDOC TESTTEST XXXX008
+    """Return an object suitable for use in a for loop that will iterate the
+       lines of the file 'f'.  Uses the xreadlines module if necessary,
+       or file.__iter__ if possible.
+    """
     if xreadlines is not None:
         return xreadlines.xreadlines(f)
     else:
@@ -1391,23 +1397,28 @@
         self.edges = newEdges
 
     def __add__(self, other):
+        "Return the union of this IntervalSet and other"
         r = self.copy()
         r += other
         return r
 
     def __sub__(self, other):
+        "Return the disjunction of this IntervalSet and other"
         r = self.copy()
         r -= other
         return r
 
     def __mul__(self, other):
+        "Return the intersection of this IntervalSet and other"
         r = self.copy()
         r *= other
         return r
 
     def getIntervalContaining(self, point):
-        """DOCDOC"""
-        #XXXX008 test
+        """If this set has any interval containing 'point', return
+           a 2-tuple containing the start and end of that interval.
+           Otherwise return (None,None).
+        """
         idx = bisect.bisect(self.edges, (point, '-'))
         if idx < len(self.edges) and self.edges[idx][1] == '-':
             return (self.edges[idx-1][0], self.edges[idx][0])
@@ -1444,8 +1455,7 @@
         return s
 
     def spanLength(self):
-        """DOCDOC"""
-        #XXXX008 testme
+        """Return the sum of the lengths of the intervals in this set."""
         r = 0
         for i in xrange(0, len(self.edges), 2):
             r += self.edges[i+1][0] - self.edges[i][0]
@@ -1604,6 +1614,7 @@
     # filename--the name of the file to lock
     # count--the recursion depth of the lock; 0 is unlocked.
     # fd--If fd>1, a file descriptor open to 'filename'.  Otherwise, None.
+    # rlock--a lock controlling access to this data structure.
     def __init__(self, filename):
         """Create a new Lockfile object to acquire and release a lock on
            'filename'"""