# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1422988178 -3600
# Node ID 4fbb7ffae1ecf54271c9eb78dcaa16d64a316094
# Parent  22add687b22b5ea626094ee3171292ae552054ef
Added function docstrings.

diff -r 22add687b22b -r 4fbb7ffae1ec imiptools/dates.py
--- a/imiptools/dates.py	Tue Feb 03 18:44:48 2015 +0100
+++ b/imiptools/dates.py	Tue Feb 03 19:29:38 2015 +0100
@@ -36,6 +36,9 @@
 match_datetime_icalendar = re.compile(datetime_icalendar_regexp_str, re.UNICODE).match
 
 def to_utc_datetime(dt):
+
+    "Return a datetime corresponding to 'dt' in the UTC time zone."
+
     if not dt:
         return None
     elif isinstance(dt, datetime):
@@ -44,6 +47,12 @@
         return dt
 
 def to_timezone(dt, name):
+
+    """
+    Return a datetime corresponding to 'dt' in the time regime having the given
+    'name'.
+    """
+
     try:
         tz = name and timezone(name) or None
     except UnknownTimeZoneError:
@@ -51,6 +60,9 @@
     return to_tz(dt, tz)
 
 def to_tz(dt, tz):
+
+    "Return a datetime corresponding to 'dt' employing the pytz.timezone 'tz'."
+
     if tz is not None and isinstance(dt, datetime):
         if not dt.tzinfo:
             return tz.localize(dt)
@@ -60,6 +72,9 @@
         return dt
 
 def format_datetime(dt):
+
+    "Format 'dt' as an iCalendar-compatible string."
+
     if not dt:
         return None
     elif isinstance(dt, datetime):
@@ -71,6 +86,9 @@
         return dt.strftime("%Y%m%d")
 
 def get_datetime_item(dt):
+
+    "Return an iCalendar-compatible string and attributes for 'dt'."
+
     if not dt:
         return None, None
     value = format_datetime(dt)
@@ -174,6 +192,9 @@
         )
 
 def get_timestamp():
+
+    "Return the current time as an iCalendar-compatible string."
+
     return format_datetime(to_timezone(datetime.utcnow(), "UTC"))
 
 # vim: tabstop=4 expandtab shiftwidth=4