From 3ff1ec0c2586f472022ce52e2c0062cea7ea2e71 Mon Sep 17 00:00:00 2001
From: Mahmoud Hashemi <mahmoud@hatnote.com>
Date: Fri, 3 Apr 2015 01:49:21 -0700
Subject: [PATCH] tzutils docs and docstrings

---
 boltons/tzutils.py | 42 ++++++++++++++++++++++++++++++++----------
 docs/tzutils.rst   | 21 +++++++++++++++++----
 2 files changed, 49 insertions(+), 14 deletions(-)

diff --git a/boltons/tzutils.py b/boltons/tzutils.py
index f5a7c49..7e2d635 100644
--- a/boltons/tzutils.py
+++ b/boltons/tzutils.py
@@ -1,28 +1,38 @@
 # -*- coding: utf-8 -*-
-"""\
-The Python ``datetime`` module documentation describe how to
-create a ``datetime``-compatible "tzinfo" object. It even provides a
-few examples.
+"""The Python :mod:`datetime` module's documentation describes how
+to create a :class:`datetime.datetime`-compatible
+:class:`datetime.tzinfo` subtype. It even provides a few examples.
+
+The following module defines usable forms of the timezones in those
+docs, as well as a couple other useful ones, :data:`UTC` (aka GMT) and
+:data:`LocalTZ` (representing the local timezone). For timezones
+beyond these, as well as a higher degree of accuracy, check out `pytz`_.
+
+.. _pytz: https://pypi.python.org/pypi/pytz
 
-The following module defines those timezones and a couple other useful
-ones, UTC (aka GMT) and Local (representing the local timezone). For
-timezones beyond this, check out ``pytz``
 """
 
 
 import time
 from datetime import tzinfo, timedelta, datetime
 
-from timeutils import total_seconds
+from timeutils import total_seconds  # TODO
 
-# Basic timezones cribbed from etavta and Python docs. Beyond this, look
-# to pytz.
+# Basic timezones cribbed from etavta and Python docs.
 
 ZERO = timedelta(0)
 HOUR = timedelta(hours=1)
 
 
 class ConstantTZInfo(tzinfo):
+    """
+    A :class:`datetime.tzinfo` subtype whose *offset* remains constant
+    (no daylight savings).
+
+    Args:
+        name (str): Name of the timezone.
+        offset (datetime.timedelta): Offset of the timezone.
+    """
     def __init__(self, name="ConstantTZ", offset=ZERO):
         self.name = name
         self.offset = offset
@@ -49,6 +59,10 @@ UTC = ConstantTZInfo('UTC')
 
 
 class LocalTZInfo(tzinfo):
+    """The ``LocalTZInfo`` type takes data available in the time module about
+    the local timezone and makes a practical tzinfo to represent the
+    timezone settings of the operating system.
+    """
     _std_offset = timedelta(seconds=-time.timezone)
     _dst_offset = _std_offset
     if time.daylight:
@@ -73,6 +87,9 @@ class LocalTZInfo(tzinfo):
     def tzname(self, dt):
         return time.tzname[self.is_dst(dt)]
 
+    def __repr__(self):
+        return '%s()' % self.__class__.__name__
+
 
 LocalTZ = LocalTZInfo()
 
@@ -111,6 +128,11 @@ DSTEND_1967_1986 = DSTEND_1987_2006
 
 
 class USTimeZone(tzinfo):
+    """Copied directly from the Python docs, the ``USTimeZone`` is a
+    :class:`datetime.tzinfo` subtype used to create the
+    :data:`Eastern`, :data:`Central`, :data:`Mountain`, and
+    :data:`Pacific` tzinfo types.
+    """
     def __init__(self, hours, reprname, stdname, dstname):
         self.stdoffset = timedelta(hours=hours)
         self.reprname = reprname
diff --git a/docs/tzutils.rst b/docs/tzutils.rst
index 7fa7304..c83d2d8 100644
--- a/docs/tzutils.rst
+++ b/docs/tzutils.rst
@@ -1,6 +1,19 @@
 ``tzutils`` - Barebone timezones
-=======
-
+================================
 .. automodule:: boltons.tzutils
-   :members:
-   :undoc-members:
+
+General timezones
+-----------------
+.. autoattribute:: boltons.tzutils.UTC
+.. autodata:: boltons.tzutils.LocalTZ
+
+.. autoclass:: boltons.tzutils.ConstantTZInfo
+
+US timezones
+------------
+.. autoattribute:: boltons.tzutils.Eastern
+.. autoattribute:: boltons.tzutils.Central
+.. autoattribute:: boltons.tzutils.Mountain
+.. autoattribute:: boltons.tzutils.Pacific
+
+.. autoclass:: boltons.tzutils.USTimeZone