Document Date conversions. Closes #10368 [chuyeow]

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

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

@@ -23,6 +23,21 @@ def self.included(base) #:nodoc:
           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:
+        #   date = Date.new(2007, 11, 10)       # => Sat, 10 Nov 2007
+        #
+        #   date.to_formatted_s(:db)            # => "2007-11-10"
+        #   date.to_s(:db)                      # => "2007-11-10"
+        #
+        #   date.to_formatted_s(:short)         # => "10 Nov"
+        #   date.to_formatted_s(:long)          # => "November 10, 2007"
+        #   date.to_formatted_s(:long_ordinal)  # => "November 10th, 2007"
+        #   date.to_formatted_s(:rfc822)        # => "10 Nov 2007"
         def to_formatted_s(format = :default)
           if formatter = DATE_FORMATS[format]
             if formatter.respond_to?(:call)
@@ -40,18 +55,33 @@ def readable_inspect
           strftime("%a, %d %b %Y")
         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_date
           self
         end if RUBY_VERSION < '1.9'
 
-        # Converts self to a Ruby Time object; time is set to beginning of day
-        # Timezone can either be :local or :utc  (default :local)
+        # Converts a Date instance to a Time, where the time is set to the beginning of the day.
+        # The timezone can be either :local or :utc (default :local).
+        #
+        # ==== Examples:
+        #   date = Date.new(2007, 11, 10)  # => Sat, 10 Nov 2007
+        #
+        #   date.to_time                   # => Sat Nov 10 00:00:00 0800 2007
+        #   date.to_time(:local)           # => Sat Nov 10 00:00:00 0800 2007
+        #
+        #   date.to_time(:utc)             # => Sat Nov 10 00:00:00 UTC 2007
         def to_time(form = :local)
           ::Time.send("#{form}_time", year, month, day)
         end
 
-        # Converts self to a Ruby DateTime object; time is set to beginning of day
+        # Converts a Date instance to a DateTime, where the time is set to the beginning of the day
+        # and UTC offset is set to 0.
+        #
+        # ==== Example:
+        #   date = Date.new(2007, 11, 10)  # => Sat, 10 Nov 2007
+        #
+        #   date.to_datetime               # => Sat, 10 Nov 2007 00:00:00 0000
         def to_datetime
           ::DateTime.civil(year, month, day, 0, 0, 0, 0)
         end if RUBY_VERSION < '1.9'