From 240f3bdb7217ed3626f2972c5dd22dc28c8aede5 Mon Sep 17 00:00:00 2001
From: Jake Goulding <jake.goulding@gmail.com>
Date: Wed, 5 Oct 2011 22:04:02 -0400
Subject: [PATCH 1/4] Document zone_offset and ZoneOffset

---
 lib/time.rb |   25 +++++++++++++++++++++++++
 1 files changed, 25 insertions(+), 0 deletions(-)

diff --git a/lib/time.rb b/lib/time.rb
index 4eb888a..9b18d83 100644
--- a/lib/time.rb
+++ b/lib/time.rb
@@ -49,6 +49,11 @@ require 'date'
 class Time
   class << Time
 
+    #
+    # A hash of timezones mapped to hour differences from UTC. The
+    # set of time zones corresponds to the ones specified by RFC 2822
+    # and ISO 8601.
+    #
     ZoneOffset = {
       'UTC' => 0,
       # ISO 8601
@@ -66,6 +71,26 @@ class Time
       'N' => -1, 'O' => -2, 'P' => -3, 'Q' => -4,  'R' => -5,  'S' => -6,
       'T' => -7, 'U' => -8, 'V' => -9, 'W' => -10, 'X' => -11, 'Y' => -12,
     }
+
+    #
+    # Return the number of seconds the specified time zone differs
+    # from UTC.
+    #
+    # Numeric time zones that include minutes, such as
+    # <code>-10:00</code> or <code>+1330</code> will work, as will
+    # simpler hour-only time zones like <code>-10</code> or
+    # <code>+13</code>.
+    #
+    # Textual time zones listed in ZoneOffset are also supported.
+    #
+    # If the time zone does not match any of the above, +zone_offset+
+    # will check if the local time zone (both with and without
+    # potential Daylight Saving \Time changes being in effect) matches
+    # +zone+. Specifying a value for +year+ will change the year used
+    # to find the local time zone.
+    #
+    # If +zone_offset+ is unable to determine the offset, nil will be
+    # returned.
     def zone_offset(zone, year=self.now.year)
       off = nil
       zone = zone.upcase
-- 
1.7.7