# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1422984537 -3600
# Node ID b0b6ce5bbe4342aa5f9beb053c1fe4fa5ad502a5
# Parent  9d17bc8ffa199703dd1a9e35291f5ca5a895deef
Added some explanations of the various day-related functions.

diff -r 9d17bc8ffa19 -r b0b6ce5bbe43 imiptools/dates.py
--- a/imiptools/dates.py	Tue Feb 03 18:19:59 2015 +0100
+++ b/imiptools/dates.py	Tue Feb 03 18:28:57 2015 +0100
@@ -112,19 +112,62 @@
     return None
 
 def get_start_of_day(dt, tzid):
+
+    """
+    Get the start of the day in which 'dt' is positioned, using the given 'tzid'
+    to obtain a datetime in the appropriate time zone. Where time zone
+    transitions occur within a day, the zone of 'dt' may not be the eventual
+    zone of the returned object.
+    """
+
     start = datetime(dt.year, dt.month, dt.day, 0, 0)
     return to_timezone(start, tzid)
 
 def get_end_of_day(dt, tzid):
+
+    """
+    Get the end of the day in which 'dt' is positioned, using the given 'tzid'
+    to obtain a datetime in the appropriate time zone. Where time zone
+    transitions occur within a day, the zone of 'dt' may not be the eventual
+    zone of the returned object.
+    """
+
     return get_start_of_day(dt + timedelta(1), tzid)
 
 def get_start_of_next_day(dt, tzid):
+
+    """
+    Get the start of the day after the day in which 'dt' is positioned. This
+    function is intended to extend either dates or datetimes to the end of a
+    day for the purpose of generating a missing end date or datetime for an
+    event.
+
+    If 'dt' is a date and not a datetime, a plain date object for the next day
+    will be returned.
+
+    If 'dt' is a datetime, the given 'tzid' is used to obtain a datetime in the
+    appropriate time zone. Where time zone transitions occur within a day, the
+    zone of 'dt' may not be the eventual zone of the returned object.
+    """
+
     if isinstance(dt, datetime):
         return get_end_of_day(dt, tzid)
     else:
         return dt + timedelta(1)
 
 def ends_on_same_day(dt, end, tzid):
+
+    """
+    Return whether 'dt' ends on the same day as 'end', testing the date
+    components of 'dt' and 'end' against each other, but also testing whether
+    'end' is the actual end of the day in which 'dt' is positioned.
+
+    Since time zone transitions may occur within a day, 'tzid' is required to
+    determine the end of the day in which 'dt' is positioned, using the zone
+    appropriate at that point in time, not necessarily the zone applying to
+    'dt'.
+    """
+
     return (
         dt.date() == end.date() or
         end == get_end_of_day(dt, tzid)