Adding documentation for time zone features

1 files changed, 21 insertions, 0 deletions

diff --git a/activesupport/lib/active_support/values/time_zone.rb b/activesupport/lib/active_support/values/time_zone.rb
index f522b64108..5340b5ed28 100644
--- a/activesupport/lib/active_support/values/time_zone.rb
+++ b/activesupport/lib/active_support/values/time_zone.rb
@@ -1,3 +1,24 @@
+# The TimeZone class serves as a wrapper around TZInfo::Timezone instances. It allows us to do the following:
+#
+#   * limit the set of zones provided by TZInfo to a meaningful subset of 142 zones
+#   * retrieve and display zones with a friendlier name (e.g., "Eastern Time (US & Canada)" instead of "America/New_York")
+#   * lazily load TZInfo::Timezone instances only when they're needed
+#   * create ActiveSupport::TimeWithZone instances via TimeZone #local, #parse, #at and #now methods
+# 
+# If you set config.time_zone in the Rails Initializer, you can access this TimeZone object via Time.zone:
+#
+#   # environment.rb:
+#   Rails::Initializer.run do |config|
+#     config.time_zone = "Eastern Time (US & Canada)"
+#   end
+#
+#   Time.zone       # => #<TimeZone:0x514834...>
+#   Time.zone.name  # => "Eastern Time (US & Canada)"
+#   Time.zone.now   # => Sun, 18 May 2008 14:30:44 EDT -04:00
+#
+# The version of TZInfo bundled with ActiveSupport only includes the definitions necessary to support the zones 
+# defined by the TimeZone class. If you need to use zones that aren't defined by TimeZone, you'll need to install the TZInfo gem
+# (if a recent version of the gem is installed locally, this will be used instead of the bundled version.)
 class TimeZone
   unless const_defined?(:MAPPING)
     # Keys are Rails TimeZone names, values are TZInfo identifiers