# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1423608062 -3600
# Node ID d7119b08b02a80c28fac501034e504f2322a2021
# Parent  3b9f6e6504d49e9f32e5379fbd29e03061baa5b8
Added docstrings.

diff -r 3b9f6e6504d4 -r d7119b08b02a vRecurrence.py
--- a/vRecurrence.py	Tue Feb 10 23:32:26 2015 +0100
+++ b/vRecurrence.py	Tue Feb 10 23:41:02 2015 +0100
@@ -284,9 +284,21 @@
 # Datetime arithmetic.
 
 def combine(t1, t2):
+
+    """
+    Combine tuples 't1' and 't2', returning a copy of 't1' filled with values
+    from 't2' in positions where 0 appeared in 't1'.
+    """
+
     return tuple(map(lambda x, y: x or y, t1, t2))
 
 def scale(interval, pos):
+
+    """
+    Scale the given 'interval' value to the indicated position 'pos', returning
+    a tuple with leading zero elements and 'interval' at the stated position.
+    """
+
     return (0,) * pos + (interval,)
 
 def get_seconds(t):
@@ -333,6 +345,9 @@
         return to_tuple(d + s, len(t))
 
 def to_tuple(d, n=None):
+
+    "Return 'd' as a tuple, optionally trimming the result to 'n' positions."
+
     if not isinstance(d, date):
         return d
     if n is None:
@@ -343,6 +358,9 @@
     return d.timetuple()[:n]
 
 def get_first_day(first_day, weekday):
+
+    "Return the first occurrence at or after 'first_day' of 'weekday'."
+
     first_day = date(*first_day)
     first_weekday = first_day.isoweekday()
     if first_weekday > weekday:
@@ -351,6 +369,9 @@
         return first_day + timedelta(weekday - first_weekday)
 
 def get_last_day(last_day, weekday):
+
+    "Return the last occurrence at or before 'last_day' of 'weekday'."
+
     last_day = date(*last_day)
     last_weekday = last_day.isoweekday()
     if last_weekday < weekday:
@@ -599,6 +620,12 @@
     return selectors[0]
 
 def get_selector(dt, qualifiers):
+
+    """
+    Combine the initial datetime 'dt' with the given 'qualifiers', returning an
+    object that can be used to select recurrences described by the 'qualifiers'.
+    """
+
     dt = to_tuple(dt)
     return connect_selectors(combine_datetime_with_qualifiers(dt, qualifiers))