revised conventions in time zone related docs

activerecord/lib/active_record/attribute_methods.rb

@@ -162,8 +162,8 @@ def define_read_method_for_serialized_attribute(attr_name)
           evaluate_attribute_method attr_name, "def #{attr_name}; unserialize_attribute('#{attr_name}'); end"
         end
         
-        # Defined for all datetime and timestamp attributes when time_zone_aware_attributes are enabled.
-        # This enhanced read method automatically converts the UTC time stored in the database to the time zone stored in Time.zone
+        # Defined for all +datetime+ and +timestamp+ attributes when +time_zone_aware_attributes+ are enabled.
+        # This enhanced read method automatically converts the UTC time stored in the database to the time zone stored in Time.zone.
         def define_read_method_for_time_zone_conversion(attr_name)
           method_body = <<-EOV
             def #{attr_name}(reload = false)
@@ -176,7 +176,7 @@ def #{attr_name}(reload = false)
           evaluate_attribute_method attr_name, method_body
         end
 
-        # Define an attribute ? method.
+        # Defines a predicate method <tt>attr_name?</tt>.
         def define_question_method(attr_name)
           evaluate_attribute_method attr_name, "def #{attr_name}?; query_attribute('#{attr_name}'); end", "#{attr_name}?"
         end
@@ -185,7 +185,7 @@ def define_write_method(attr_name)
           evaluate_attribute_method attr_name, "def #{attr_name}=(new_value);write_attribute('#{attr_name}', new_value);end", "#{attr_name}="
         end
         
-        # Defined for all datetime and timestamp attributes when time_zone_aware_attributes are enabled.
+        # Defined for all +datetime+ and +timestamp+ attributes when +time_zone_aware_attributes+ are enabled.
         # This enhanced write method will automatically convert the time passed to it to the zone stored in Time.zone.
         def define_write_method_for_time_zone_conversion(attr_name)
           method_body = <<-EOV

activesupport/lib/active_support/core_ext/time/zones.rb

@@ -10,21 +10,21 @@ module ClassMethods
           attr_accessor :zone_default
           
           # Returns the TimeZone for the current request, if this has been set (via Time.zone=). 
-          # If Time.zone has not been set for the current request, returns the TimeZone specified in config.time_zone
+          # If Time.zone has not been set for the current request, returns the TimeZone specified in <tt>config.time_zone</tt>.
           def zone
             Thread.current[:time_zone] || zone_default
           end
 
-          # Sets Time.zone to a TimeZone object for the current request/thread. 
+          # Sets <tt>Time.zone</tt> to a TimeZone object for the current request/thread. 
           #
           # This method accepts any of the following:
           #
-          #   * a Rails TimeZone object
-          #   * an identifier for a Rails TimeZone object (e.g., "Eastern Time (US & Canada)", -5.hours)
-          #   * a TZInfo::Timezone object
-          #   * an identifier for a TZInfo::Timezone object (e.g., "America/New_York")
+          # * A Rails TimeZone object.
+          # * An identifier for a Rails TimeZone object (e.g., "Eastern Time (US & Canada)", <tt>-5.hours</tt>).
+          # * A TZInfo::Timezone object.
+          # * An identifier for a TZInfo::Timezone object (e.g., "America/New_York").
           #
-          # Here's an example of how you might set Time.zone on a per request basis -- current_user.time_zone
+          # Here's an example of how you might set <tt>Time.zone</tt> on a per request basis -- <tt>current_user.time_zone</tt>
           # just needs to return a string identifying the user's preferred TimeZone:
           #
           #   class ApplicationController < ActionController::Base
@@ -38,7 +38,7 @@ def zone=(time_zone)
             Thread.current[:time_zone] = get_zone(time_zone)
           end
           
-          # Allows override of Time.zone locally inside supplied block; resets Time.zone to existing value when done
+          # Allows override of <tt>Time.zone</tt> locally inside supplied block; resets <tt>Time.zone</tt> to existing value when done.
           def use_zone(time_zone)
             old_zone, ::Time.zone = ::Time.zone, get_zone(time_zone)
             yield
@@ -46,7 +46,7 @@ def use_zone(time_zone)
             ::Time.zone = old_zone
           end
           
-          # Returns Time.zone.now when config.time_zone is set, otherwise just returns Time.now.
+          # Returns <tt>Time.zone.now</tt> when <tt>config.time_zone</tt> is set, otherwise just returns <tt>Time.now</tt>.
           def current
             ::Time.zone_default ? ::Time.zone.now : ::Time.now
           end
@@ -65,16 +65,16 @@ def get_zone(time_zone)
             end
         end
         
-        # Returns the simultaneous time in Time.zone.
+        # Returns the simultaneous time in <tt>Time.zone</tt>.
         #
         #   Time.zone = 'Hawaii'         # => 'Hawaii'
         #   Time.utc(2000).in_time_zone  # => Fri, 31 Dec 1999 14:00:00 HST -10:00
         #
-        # This method is similar to Time#localtime, except that it uses Time.zone as the local zone
+        # This method is similar to Time#localtime, except that it uses <tt>Time.zone</tt> as the local zone
         # instead of the operating system's time zone.
         #
         # You can also pass in a TimeZone instance or string that identifies a TimeZone as an argument, 
-        # and the conversion will be based on that zone instead of Time.zone.
+        # and the conversion will be based on that zone instead of <tt>Time.zone</tt>.
         #
         #   Time.utc(2000).in_time_zone('Alaska')  # => Fri, 31 Dec 1999 15:00:00 AKST -09:00
         def in_time_zone(zone = ::Time.zone)

activesupport/lib/active_support/time_with_zone.rb

 require 'tzinfo'
 module ActiveSupport
   # A Time-like class that can represent a time in any time zone. Necessary because standard Ruby Time instances are 
-  # limited to UTC and the system's ENV['TZ'] zone.
+  # limited to UTC and the system's <tt>ENV['TZ']</tt> zone.
   #
-  # You shouldn't ever need to create a TimeWithZone instance directly via .new -- instead, Rails provides the methods
-  # #local, #parse, #at and #now on TimeZone instances, and #in_time_zone on Time and DateTime instances, for a more
+  # You shouldn't ever need to create a TimeWithZone instance directly via <tt>new</tt> -- instead, Rails provides the methods
+  # +local+, +parse+, +at+ and +now+ on TimeZone instances, and +in_time_zone+ on Time and DateTime instances, for a more
   # user-friendly syntax. Examples:
   #
   #   Time.zone = 'Eastern Time (US & Canada)'        # => 'Eastern Time (US & Canada)'
@@ -38,12 +38,12 @@ def initialize(utc_time, time_zone, local_time = nil, period = nil)
       @period = @utc ? period : get_period_and_ensure_valid_local_time
     end
   
-    # Returns a Time or DateTime instance that represents the time in time_zone
+    # Returns a Time or DateTime instance that represents the time in +time_zone+.
     def time
       @time ||= period.to_local(@utc)
     end
 
-    # Returns a Time or DateTime instance that represents the time in UTC
+    # Returns a Time or DateTime instance that represents the time in UTC.
     def utc
       @utc ||= period.to_utc(@time)
     end
@@ -52,18 +52,18 @@ def utc
     alias_method :getutc, :utc
     alias_method :gmtime, :utc
   
-    # Returns the underlying TZInfo::TimezonePeriod
+    # Returns the underlying TZInfo::TimezonePeriod.
     def period
       @period ||= time_zone.period_for_utc(@utc)
     end
 
-    # Returns the simultaneous time in Time.zone, or the specified zone
+    # Returns the simultaneous time in <tt>Time.zone</tt>, or the specified zone.
     def in_time_zone(new_zone = ::Time.zone)
       return self if time_zone == new_zone
       utc.in_time_zone(new_zone)
     end
   
-    # Returns a Time.local() instance of the simultaneous time in your system's ENV['TZ'] zone
+    # Returns a <tt>Time.local()</tt> instance of the simultaneous time in your system's <tt>ENV['TZ']</tt> zone
     def localtime
       utc.getlocal
     end
@@ -146,7 +146,7 @@ def strftime(format)
       time.strftime(format)
     end
   
-    # Use the time in UTC for comparisons
+    # Use the time in UTC for comparisons.
     def <=>(other)
       utc <=> other
     end
@@ -159,7 +159,7 @@ def eql?(other)
       utc == other
     end
     
-    # If wrapped #time is a DateTime, use DateTime#since instead of <tt>+</tt>.
+    # If wrapped +time+ is a DateTime, use DateTime#since instead of <tt>+</tt>.
     # Otherwise, just pass on to +method_missing+.
     def +(other)
       result = utc.acts_like?(:date) ? utc.since(other) : utc + other rescue utc.since(other)
@@ -225,7 +225,7 @@ def to_datetime
       utc.to_datetime.new_offset(Rational(utc_offset, 86_400))
     end
     
-    # so that self acts_like?(:time)
+    # So that self acts_like?(:time).
     def acts_like_time?
       true
     end
@@ -236,7 +236,7 @@ def is_a?(klass)
     end
     alias_method :kind_of?, :is_a?
   
-    # Neuter freeze because freezing can cause problems with lazy loading of attributes
+    # Neuter freeze because freezing can cause problems with lazy loading of attributes.
     def freeze
       self
     end
@@ -249,14 +249,14 @@ def marshal_load(variables)
       initialize(variables[0], ::Time.send!(:get_zone, variables[1]), variables[2])
     end
   
-    # Ensure proxy class responds to all methods that underlying time instance responds to
+    # Ensure proxy class responds to all methods that underlying time instance responds to.
     def respond_to?(sym)
       # consistently respond false to acts_like?(:date), regardless of whether #time is a Time or DateTime
       return false if sym.to_s == 'acts_like_date?'
       super || time.respond_to?(sym)
     end
   
-    # Send the missing method to time instance, and wrap result in a new TimeWithZone with the existing time_zone
+    # Send the missing method to +time+ instance, and wrap result in a new TimeWithZone with the existing +time_zone+.
     def method_missing(sym, *args, &block)
       result = time.__send__(sym, *args, &block)
       result.acts_like?(:time) ? self.class.new(nil, time_zone, result) : result

activesupport/lib/active_support/values/time_zone.rb

 # 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
+# * 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's +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:
+# If you set <tt>config.time_zone</tt> in the Rails Initializer, you can access this TimeZone object via <tt>Time.zone</tt>:
 #
 #   # environment.rb:
 #   Rails::Initializer.run do |config|