Enhance documentation for Active Support's Time Conversion functions....

Enhance documentation for Active Support's Time Conversion functions. [rsanheim, jeremymcanally, chuyeow] Closes #7164


git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@8278 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

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

@@ -19,6 +19,22 @@ def self.included(base)
           end
         end
 
+        # Convert to a formatted string - see DATE_FORMATS for predefined formats.
+        # You can also add your own formats to the DATE_FORMATS constant and use them with this method.
+        #
+        # This method is also aliased as <tt>to_s</tt>.
+        #
+        # ==== Examples:
+        #   time = Time.now                     # => Thu Jan 18 06:10:17 CST 2007
+        #
+        #   time.to_formatted_s(:time)          # => "06:10:17"
+        #   time.to_s(:time)                    # => "06:10:17"
+        #
+        #   time.to_formatted_s(:db)            # => "2007-01-18 06:10:17"
+        #   time.to_formatted_s(:short)         # => "18 Jan 06:10"
+        #   time.to_formatted_s(:long)          # => "January 18, 2007 06:10"
+        #   time.to_formatted_s(:long_ordinal)  # => "January 18th, 2007 06:10"
+        #   time.to_formatted_s(:rfc822)        # => "Thu, 18 Jan 2007 06:10:17 -0600"
         def to_formatted_s(format = :default)
           if formatter = DATE_FORMATS[format]
             if formatter.respond_to?(:call)
@@ -31,17 +47,44 @@ def to_formatted_s(format = :default)
           end
         end
 
-        # Converts self to a Ruby Date object; time portion is discarded
+        # Convert a Time object to a Date, dropping hour, minute, and second precision.
+        #
+        # ==== Examples
+        #   my_time = Time.now
+        #   # => Mon Nov 12 22:59:51 -0500 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
         def to_date
           ::Date.new(year, month, day)
         end
 
-        # To be able to keep Times, Dates and DateTimes interchangeable on conversions
+        # A method to keep Time, Date and DateTime instances interchangeable on conversions.
+        # In this case, it simply returns +self+.
         def to_time
           self
         end
 
-        # converts to a Ruby DateTime instance; preserves utc offset
+        # Converts a Time instance to a Ruby DateTime instance, preserving UTC offset.
+        #
+        # ==== Examples
+        #   my_time = Time.now
+        #   # => Mon Nov 12 23:04:21 -0500 2007
+        #
+        #   my_time.to_datetime
+        #   # => Mon, 12 Nov 2007 23:04:21 -0500
+        #
+        #   your_time = Time.parse("1/13/2009 1:13:03 P.M.")
+        #   # => Tue Jan 13 13:13:03 -0500 2009
+        #
+        #   your_time.to_datetime
+        #   # => Tue, 13 Jan 2009 13:13:03 -0500
         def to_datetime
           ::DateTime.civil(year, month, day, hour, min, sec, Rational(utc_offset, 86400))
         end