Merge docrails.

Signed-off-by: Pratik Naik <pratiknaik@gmail.com>

14 files changed, 124 insertions, 122 deletions

diff --git a/activesupport/lib/active_support/core_ext/hash/conversions.rb b/activesupport/lib/active_support/core_ext/hash/conversions.rb
index a023118885..2c606b401b 100644
--- a/activesupport/lib/active_support/core_ext/hash/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/hash/conversions.rb
@@ -212,7 +212,7 @@ module ActiveSupport #:nodoc:
                     nil
                   # If the type is the only element which makes it then 
                   # this still makes the value nil, except if type is
-                  # a xml node(where type['value'] is a Hash)
+                  # a XML node(where type['value'] is a Hash)
                   elsif value['type'] && value.size == 1 && !value['type'].is_a?(::Hash)
                     nil
                   else
diff --git a/activesupport/lib/active_support/core_ext/integer/even_odd.rb b/activesupport/lib/active_support/core_ext/integer/even_odd.rb
index cfc6b4c6d6..b1d1e28062 100644
--- a/activesupport/lib/active_support/core_ext/integer/even_odd.rb
+++ b/activesupport/lib/active_support/core_ext/integer/even_odd.rb
@@ -3,10 +3,14 @@ module ActiveSupport #:nodoc:
     module Integer #:nodoc:
       # For checking if a fixnum is even or odd.
       #
-      #   1.even? # => false
-      #   1.odd?  # => true
-      #   2.even? # => true
-      #   2.odd?  # => false
+      #   2.even?  # => true
+      #   2.odd?   # => false
+      #   1.even?  # => false
+      #   1.odd?   # => true
+      #   0.even?  # => true
+      #   0.odd?   # => false
+      #   -1.even? # => false
+      #   -1.odd?  # => true
       module EvenOdd
         def multiple_of?(number)
           self % number == 0
diff --git a/activesupport/lib/active_support/core_ext/object/misc.rb b/activesupport/lib/active_support/core_ext/object/misc.rb
index a3637d7a8a..8384a12327 100644
--- a/activesupport/lib/active_support/core_ext/object/misc.rb
+++ b/activesupport/lib/active_support/core_ext/object/misc.rb
@@ -48,7 +48,7 @@ class Object
     yield ActiveSupport::OptionMerger.new(self, options)
   end
   
-  # A duck-type assistant method. For example, ActiveSupport extends Date
+  # A duck-type assistant method. For example, Active Support extends Date
   # to define an acts_like_date? method, and extends Time to define
   # acts_like_time?. As a result, we can do "x.acts_like?(:time)" and
   # "x.acts_like?(:date)" to do duck-type-safe comparisons, since classes that
diff --git a/activesupport/lib/active_support/core_ext/string/unicode.rb b/activesupport/lib/active_support/core_ext/string/unicode.rb
index ba16d4d866..5e20534d1d 100644
--- a/activesupport/lib/active_support/core_ext/string/unicode.rb
+++ b/activesupport/lib/active_support/core_ext/string/unicode.rb
@@ -17,17 +17,17 @@ module ActiveSupport #:nodoc:
           # string overrides can also be called through the +chars+ proxy.
           #
           #   name = 'Claus Müller'
-          #   name.reverse  #=> "rell??M sualC"
-          #   name.length   #=> 13
+          #   name.reverse              # => "rell??M sualC"
+          #   name.length               # => 13
           #
-          #   name.chars.reverse.to_s   #=> "rellüM sualC"
-          #   name.chars.length         #=> 12
+          #   name.chars.reverse.to_s   # => "rellüM sualC"
+          #   name.chars.length         # => 12
           #   
           #
           # All the methods on the chars proxy which normally return a string will return a Chars object. This allows
           # method chaining on the result of any of these methods.
           #
-          #   name.chars.reverse.length #=> 12
+          #   name.chars.reverse.length # => 12
           #
           # The Char object tries to be as interchangeable with String objects as possible: sorting and comparing between
           # String and Char work like expected. The bang! methods change the internal string representation in the Chars
diff --git a/activesupport/lib/active_support/core_ext/time/conversions.rb b/activesupport/lib/active_support/core_ext/time/conversions.rb
index edca5b8a98..9054008309 100644
--- a/activesupport/lib/active_support/core_ext/time/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/time/conversions.rb
@@ -59,7 +59,7 @@ module ActiveSupport #:nodoc:
         # Converts a Time object to a Date, dropping hour, minute, and second precision.
         #
         #   my_time = Time.now  # => Mon Nov 12 22:59:51 -0500 2007
-        #   my_time.to_date     #=> Mon, 12 Nov 2007
+        #   my_time.to_date     # => Mon, 12 Nov 2007
         #
         #   your_time = Time.parse("1/13/2009 1:13:03 P.M.")  # => Tue Jan 13 13:13:03 -0500 2009
         #   your_time.to_date                                 # => Tue, 13 Jan 2009
diff --git a/activesupport/lib/active_support/core_ext/time/zones.rb b/activesupport/lib/active_support/core_ext/time/zones.rb
index cf28d0fa95..079ecdd48e 100644
--- a/activesupport/lib/active_support/core_ext/time/zones.rb
+++ b/activesupport/lib/active_support/core_ext/time/zones.rb
@@ -10,21 +10,21 @@ module ActiveSupport #:nodoc:
           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 <tt>Time.zone</tt> 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 @@ module ActiveSupport #:nodoc:
             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 @@ module ActiveSupport #:nodoc:
             ::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 @@ module ActiveSupport #:nodoc:
             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)
diff --git a/activesupport/lib/active_support/deprecation.rb b/activesupport/lib/active_support/deprecation.rb
index 6aa379b550..758aef5445 100644
--- a/activesupport/lib/active_support/deprecation.rb
+++ b/activesupport/lib/active_support/deprecation.rb
@@ -144,8 +144,8 @@ module ActiveSupport
         end
     end
 
-    # Stand-in for @request, @attributes, @params, etc which emits deprecation
-    # warnings on any method call (except #inspect).
+    # Stand-in for <tt>@request</tt>, <tt>@attributes</tt>, <tt>@params</tt>, etc.
+    # which emits deprecation warnings on any method call (except +inspect+).
     class DeprecatedInstanceVariableProxy #:nodoc:
       silence_warnings do
         instance_methods.each { |m| undef_method m unless m =~ /^__/ }
diff --git a/activesupport/lib/active_support/inflector.rb b/activesupport/lib/active_support/inflector.rb
index 0fd44324bb..a4fd619317 100644
--- a/activesupport/lib/active_support/inflector.rb
+++ b/activesupport/lib/active_support/inflector.rb
@@ -109,13 +109,13 @@ module Inflector
 
   # Returns the plural form of the word in the string.
   #
-  # Examples
-  #   "post".pluralize #=> "posts"
-  #   "octopus".pluralize #=> "octopi"
-  #   "sheep".pluralize #=> "sheep"
-  #   "words".pluralize #=> "words"
-  #   "the blue mailman".pluralize #=> "the blue mailmen"
-  #   "CamelOctopus".pluralize #=> "CamelOctopi"
+  # Examples:
+  #   "post".pluralize             # => "posts"
+  #   "octopus".pluralize          # => "octopi"
+  #   "sheep".pluralize            # => "sheep"
+  #   "words".pluralize            # => "words"
+  #   "the blue mailman".pluralize # => "the blue mailmen"
+  #   "CamelOctopus".pluralize     # => "CamelOctopi"
   def pluralize(word)
     result = word.to_s.dup
 
@@ -127,15 +127,15 @@ module Inflector
     end
   end
 
-  # The reverse of pluralize, returns the singular form of a word in a string.
+  # The reverse of +pluralize+, returns the singular form of a word in a string.
   #
-  # Examples
-  #   "posts".singularize #=> "post"
-  #   "octopi".singularize #=> "octopus"
-  #   "sheep".singluarize #=> "sheep"
-  #   "word".singluarize #=> "word"
-  #   "the blue mailmen".singularize #=> "the blue mailman"
-  #   "CamelOctopi".singularize #=> "CamelOctopus"
+  # Examples:
+  #   "posts".singularize            # => "post"
+  #   "octopi".singularize           # => "octopus"
+  #   "sheep".singluarize            # => "sheep"
+  #   "word".singluarize             # => "word"
+  #   "the blue mailmen".singularize # => "the blue mailman"
+  #   "CamelOctopi".singularize      # => "CamelOctopus"
   def singularize(word)
     result = word.to_s.dup
 
@@ -147,16 +147,16 @@ module Inflector
     end
   end
 
-  # By default, camelize converts strings to UpperCamelCase. If the argument to camelize
-  # is set to ":lower" then camelize produces lowerCamelCase.
+  # By default, +camelize+ converts strings to UpperCamelCase. If the argument to +camelize+
+  # is set to <tt>:lower</tt> then +camelize+ produces lowerCamelCase.
   #
-  # camelize will also convert '/' to '::' which is useful for converting paths to namespaces
+  # +camelize+ will also convert '/' to '::' which is useful for converting paths to namespaces.
   #
-  # Examples
-  #   "active_record".camelize #=> "ActiveRecord"
-  #   "active_record".camelize(:lower) #=> "activeRecord"
-  #   "active_record/errors".camelize #=> "ActiveRecord::Errors"
-  #   "active_record/errors".camelize(:lower) #=> "activeRecord::Errors"
+  # Examples:
+  #   "active_record".camelize                # => "ActiveRecord"
+  #   "active_record".camelize(:lower)        # => "activeRecord"
+  #   "active_record/errors".camelize         # => "ActiveRecord::Errors"
+  #   "active_record/errors".camelize(:lower) # => "activeRecord::Errors"
   def camelize(lower_case_and_underscored_word, first_letter_in_uppercase = true)
     if first_letter_in_uppercase
       lower_case_and_underscored_word.to_s.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
@@ -166,14 +166,14 @@ module Inflector
   end
 
   # Capitalizes all the words and replaces some characters in the string to create
-  # a nicer looking title. Titleize is meant for creating pretty output. It is not
+  # a nicer looking title. +titleize+ is meant for creating pretty output. It is not
   # used in the Rails internals.
   #
-  # titleize is also aliased as as titlecase
+  # +titleize+ is also aliased as as +titlecase+.
   #
-  # Examples
-  #   "man from the boondocks".titleize #=> "Man From The Boondocks"
-  #   "x-men: the last stand".titleize #=> "X Men: The Last Stand"
+  # Examples:
+  #   "man from the boondocks".titleize # => "Man From The Boondocks"
+  #   "x-men: the last stand".titleize  # => "X Men: The Last Stand"
   def titleize(word)
     humanize(underscore(word)).gsub(/\b('?[a-z])/) { $1.capitalize }
   end
@@ -182,9 +182,9 @@ module Inflector
   #
   # Changes '::' to '/' to convert namespaces to paths.
   #
-  # Examples
-  #   "ActiveRecord".underscore #=> "active_record"
-  #   "ActiveRecord::Errors".underscore #=> active_record/errors
+  # Examples:
+  #   "ActiveRecord".underscore         # => "active_record"
+  #   "ActiveRecord::Errors".underscore # => active_record/errors
   def underscore(camel_cased_word)
     camel_cased_word.to_s.gsub(/::/, '/').
       gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
@@ -195,52 +195,52 @@ module Inflector
 
   # Replaces underscores with dashes in the string.
   #
-  # Example
-  #   "puni_puni" #=> "puni-puni"
+  # Example:
+  #   "puni_puni" # => "puni-puni"
   def dasherize(underscored_word)
     underscored_word.gsub(/_/, '-')
   end
 
-  # Capitalizes the first word and turns underscores into spaces and strips _id.
-  # Like titleize, this is meant for creating pretty output.
+  # Capitalizes the first word and turns underscores into spaces and strips a
+  # trailing "_id", if any. Like +titleize+, this is meant for creating pretty output.
   #
-  # Examples
-  #   "employee_salary" #=> "Employee salary"
-  #   "author_id" #=> "Author"
+  # Examples:
+  #   "employee_salary" # => "Employee salary"
+  #   "author_id"       # => "Author"
   def humanize(lower_case_and_underscored_word)
     lower_case_and_underscored_word.to_s.gsub(/_id$/, "").gsub(/_/, " ").capitalize
   end
 
-  # Removes the module part from the expression in the string
+  # Removes the module part from the expression in the string.
   #
-  # Examples
-  #   "ActiveRecord::CoreExtensions::String::Inflections".demodulize #=> "Inflections"
-  #   "Inflections".demodulize #=> "Inflections"
+  # Examples:
+  #   "ActiveRecord::CoreExtensions::String::Inflections".demodulize # => "Inflections"
+  #   "Inflections".demodulize                                       # => "Inflections"
   def demodulize(class_name_in_module)
     class_name_in_module.to_s.gsub(/^.*::/, '')
   end
 
   # Create the name of a table like Rails does for models to table names. This method
-  # uses the pluralize method on the last word in the string.
+  # uses the +pluralize+ method on the last word in the string.
   #
   # Examples
-  #   "RawScaledScorer".tableize #=> "raw_scaled_scorers"
-  #   "egg_and_ham".tableize #=> "egg_and_hams"
-  #   "fancyCategory".tableize #=> "fancy_categories"
+  #   "RawScaledScorer".tableize # => "raw_scaled_scorers"
+  #   "egg_and_ham".tableize     # => "egg_and_hams"
+  #   "fancyCategory".tableize   # => "fancy_categories"
   def tableize(class_name)
     pluralize(underscore(class_name))
   end
 
   # Create a class name from a plural table name like Rails does for table names to models.
   # Note that this returns a string and not a Class. (To convert to an actual class
-  # follow classify with constantize.)
+  # follow +classify+ with +constantize+.)
   #
-  # Examples
-  #   "egg_and_hams".classify #=> "EggAndHam"
-  #   "posts".classify #=> "Post"
+  # Examples:
+  #   "egg_and_hams".classify # => "EggAndHam"
+  #   "posts".classify        # => "Post"
   #
-  # Singular names are not handled correctly
-  #   "business".classify #=> "Busines"
+  # Singular names are not handled correctly:
+  #   "business".classify     # => "Busines"
   def classify(table_name)
     # strip out any leading schema name
     camelize(singularize(table_name.to_s.sub(/.*\./, '')))
@@ -250,10 +250,10 @@ module Inflector
   # +separate_class_name_and_id_with_underscore+ sets whether
   # the method should put '_' between the name and 'id'.
   #
-  # Examples
-  #   "Message".foreign_key #=> "message_id"
-  #   "Message".foreign_key(false) #=> "messageid"
-  #   "Admin::Post".foreign_key #=> "post_id"
+  # Examples:
+  #   "Message".foreign_key        # => "message_id"
+  #   "Message".foreign_key(false) # => "messageid"
+  #   "Admin::Post".foreign_key    # => "post_id"
   def foreign_key(class_name, separate_class_name_and_id_with_underscore = true)
     underscore(demodulize(class_name)) + (separate_class_name_and_id_with_underscore ? "_id" : "id")
   end
@@ -283,10 +283,10 @@ module Inflector
     Object.module_eval("::#{$1}", __FILE__, __LINE__)
   end
 
-  # Ordinalize turns a number into an ordinal string used to denote the
-  # position in an ordered sequence such as 1st, 2nd, 3rd, 4th.
+  # Turns a number into an ordinal string used to denote the position in an
+  # ordered sequence such as 1st, 2nd, 3rd, 4th.
   #
-  # Examples
+  # Examples:
   #   ordinalize(1)     # => "1st"
   #   ordinalize(2)     # => "2nd"
   #   ordinalize(1002)  # => "1002nd"
diff --git a/activesupport/lib/active_support/json.rb b/activesupport/lib/active_support/json.rb
index bbda2c9fa3..54a7becd0f 100644
--- a/activesupport/lib/active_support/json.rb
+++ b/activesupport/lib/active_support/json.rb
@@ -1,5 +1,5 @@
 module ActiveSupport
-  # If true, use ISO 8601 format for dates and times.  Otherwise, fall back to the ActiveSupport legacy format.
+  # If true, use ISO 8601 format for dates and times.  Otherwise, fall back to the Active Support legacy format.
   mattr_accessor :use_standard_json_time_format
 
   class << self
diff --git a/activesupport/lib/active_support/json/decoding.rb b/activesupport/lib/active_support/json/decoding.rb
index c58001f49f..fdb219dbf7 100644
--- a/activesupport/lib/active_support/json/decoding.rb
+++ b/activesupport/lib/active_support/json/decoding.rb
@@ -31,7 +31,7 @@ module ActiveSupport
                 if json[pos..scanner.pos-2] =~ DATE_REGEX
                   # found a date, track the exact positions of the quotes so we can remove them later.
                   # oh, and increment them for each current mark, each one is an extra padded space that bumps
-                  # the position in the final yaml output
+                  # the position in the final YAML output
                   total_marks = marks.size
                   times << pos+total_marks << scanner.pos+total_marks
                 end
diff --git a/activesupport/lib/active_support/multibyte/chars.rb b/activesupport/lib/active_support/multibyte/chars.rb
index 65114415eb..ee716de39e 100644
--- a/activesupport/lib/active_support/multibyte/chars.rb
+++ b/activesupport/lib/active_support/multibyte/chars.rb
@@ -10,7 +10,7 @@ module ActiveSupport::Multibyte #:nodoc:
   # String methods are proxied through the Chars object, and can be accessed through the +chars+ method. Methods
   # which would normally return a String object now return a Chars object so methods can be chained.
   #
-  #   "The Perfect String  ".chars.downcase.strip.normalize #=> "the perfect string"
+  #   "The Perfect String  ".chars.downcase.strip.normalize # => "the perfect string"
   #
   # Chars objects are perfectly interchangeable with String objects as long as no explicit class checks are made.
   # If certain methods do explicitly check the class, call +to_s+ before you pass chars objects to them.
diff --git a/activesupport/lib/active_support/multibyte/handlers/utf8_handler.rb b/activesupport/lib/active_support/multibyte/handlers/utf8_handler.rb
index 0166b69ac3..aa9c16f575 100644
--- a/activesupport/lib/active_support/multibyte/handlers/utf8_handler.rb
+++ b/activesupport/lib/active_support/multibyte/handlers/utf8_handler.rb
@@ -147,13 +147,11 @@ module ActiveSupport::Multibyte::Handlers #:nodoc:
       #
       #   s = "Müller"
       #   s.chars[2] = "e" # Replace character with offset 2
-      #   s
-      #   #=> "Müeler"
+      #   s # => "Müeler"
       #
       #   s = "Müller"
       #   s.chars[1, 2] = "ö" # Replace 2 characters at character offset 1
-      #   s
-      #   #=> "Möler"
+      #   s # => "Möler"
       def []=(str, *args)
         replace_by = args.pop
         # Indexed replace with regular expressions already works
@@ -183,10 +181,10 @@ module ActiveSupport::Multibyte::Handlers #:nodoc:
       # Example:
       #
       #   "¾ cup".chars.rjust(8).to_s
-      #   #=> "   ¾ cup"
+      #   # => "   ¾ cup"
       #
       #   "¾ cup".chars.rjust(8, " ").to_s # Use non-breaking whitespace
-      #   #=> "   ¾ cup"
+      #   # => "   ¾ cup"
       def rjust(str, integer, padstr=' ')
         justify(str, integer, :right, padstr)
       end
@@ -196,10 +194,10 @@ module ActiveSupport::Multibyte::Handlers #:nodoc:
       # Example:
       #
       #   "¾ cup".chars.rjust(8).to_s
-      #   #=> "¾ cup   "
+      #   # => "¾ cup   "
       #
       #   "¾ cup".chars.rjust(8, " ").to_s # Use non-breaking whitespace
-      #   #=> "¾ cup   "
+      #   # => "¾ cup   "
       def ljust(str, integer, padstr=' ')
         justify(str, integer, :left, padstr)
       end
@@ -209,10 +207,10 @@ module ActiveSupport::Multibyte::Handlers #:nodoc:
       # Example:
       #
       #   "¾ cup".chars.center(8).to_s
-      #   #=> " ¾ cup  "
+      #   # => " ¾ cup  "
       #
       #   "¾ cup".chars.center(8, " ").to_s # Use non-breaking whitespace
-      #   #=> " ¾ cup  "
+      #   # => " ¾ cup  "
       def center(str, integer, padstr=' ')
         justify(str, integer, :center, padstr)
       end
diff --git a/activesupport/lib/active_support/time_with_zone.rb b/activesupport/lib/active_support/time_with_zone.rb
index 64c935717d..ece95eeae9 100644
--- a/activesupport/lib/active_support/time_with_zone.rb
+++ b/activesupport/lib/active_support/time_with_zone.rb
@@ -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 @@ module ActiveSupport
       @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 @@ module ActiveSupport
     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
@@ -89,7 +89,7 @@ module ActiveSupport
       utc? && alternate_utc_string || utc_offset.to_utc_offset_s(colon)
     end
   
-    # Time uses #zone to display the time zone abbreviation, so we're duck-typing it
+    # Time uses +zone+ to display the time zone abbreviation, so we're duck-typing it.
     def zone
       period.zone_identifier.to_s
     end
@@ -146,7 +146,7 @@ module ActiveSupport
       time.strftime(format)
     end
   
-    # Use the time in UTC for comparisons
+    # Use the time in UTC for comparisons.
     def <=>(other)
       utc <=> other
     end
@@ -159,8 +159,8 @@ module ActiveSupport
       utc == other
     end
     
-    # If wrapped #time is a DateTime, use DateTime#since instead of #+
-    # Otherwise, just pass on to #method_missing
+    # 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)
       result.in_time_zone(time_zone)
@@ -225,18 +225,18 @@ module ActiveSupport
       utc.to_datetime.new_offset(Rational(utc_offset, 86_400))
     end
     
-    # so that self acts_like?(:time)
+    # So that +self+ <tt>acts_like?(:time)</tt>.
     def acts_like_time?
       true
     end
   
-    # Say we're a Time to thwart type checking
+    # Say we're a Time to thwart type checking.
     def is_a?(klass)
       klass == ::Time || super
     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 @@ module ActiveSupport
       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
diff --git a/activesupport/lib/active_support/values/time_zone.rb b/activesupport/lib/active_support/values/time_zone.rb
index 5340b5ed28..4d7239d8cf 100644
--- a/activesupport/lib/active_support/values/time_zone.rb
+++ b/activesupport/lib/active_support/values/time_zone.rb
@@ -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|
@@ -16,7 +16,7 @@
 #   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 
+# The version of TZInfo bundled with Active Support 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
@@ -356,7 +356,7 @@ class TimeZone
 
     # Return a TimeZone instance with the given name, or +nil+ if no
     # such TimeZone instance exists. (This exists to support the use of
-    # this class with the #composed_of macro.)
+    # this class with the +composed_of+ macro.)
     def new(name)
       self[name]
     end