Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

revised conventions in time zone related docs

  • Loading branch information...
commit 633e9b4c5656a18dc5cb1eff95d47fc1824b2c27 1 parent 1148af4
Xavier Noria fxn authored
8 activerecord/lib/active_record/attribute_methods.rb
View
@@ -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
24 activesupport/lib/active_support/core_ext/time/zones.rb
View
@@ -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)
28 activesupport/lib/active_support/time_with_zone.rb
View
@@ -1,10 +1,10 @@
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
10 activesupport/lib/active_support/values/time_zone.rb
View
@@ -1,11 +1,11 @@
# 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|
Please sign in to comment.
Something went wrong with that request. Please try again.