Document date and time to_formatted_s. Closes #10747 [leethal]

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

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

 module ActiveSupport #:nodoc:
   module CoreExtensions #:nodoc:
     module Date #:nodoc:
-      # Getting dates in different convenient string representations and other objects
+      # Getting datetimes in different convenient string representations and other objects.
+      #
+      # == Adding your own time formats in to_formatted_s
+      # You can add your own time formats by merging them into the DATE_FORMATS constant. Use a string with
+      # Ruby's strftime formatting (http://ruby-doc.org/core/classes/Time.html#M000297), or
+      # pass a lambda. The lambda yields the instance to_formatted_s is called on, so that calculations
+      # can be performed on that instance. This is handy when Ruby's strftime formatting is insufficient. See
+      # the +short_ordinal+ example below.
+      #
+      # See DATE_FORMATS for the list of built-in formats, and to_formatted_s for implementation details.
+      #
+      # === Examples:
+      #   # config/initializers/time_formats.rb
+      #   ActiveSupport::CoreExtensions::Date::Conversions::DATE_FORMATS.merge!(
+      #     :month_and_year => "%B %Y",
+      #     :short_ordinal => lambda { |time| time.strftime("%B #{time.day.ordinalize}") }
+      #   )
+      #
+      # Calling it on a Time instance:
+      #
+      #   Time.now.to_s(:short_ordinal)
       module Conversions
         DATE_FORMATS = {
           :short        => "%e %b",

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

 module ActiveSupport #:nodoc:
   module CoreExtensions #:nodoc:
     module DateTime #:nodoc:
-      # Getting datetimes in different convenient string representations and other objects
+      # Getting datetimes in different convenient string representations and other objects.
+      #
+      # == Adding your own time formats in to_formatted_s
+      # You can add your own time formats by merging them into the  ::Time::Conversions::DATE_FORMATS constant. Use a string with
+      # Ruby's strftime formatting (http://ruby-doc.org/core/classes/Time.html#M000297), or
+      # pass a lambda. The lambda yields the instance to_formatted_s is called on, so that calculations
+      # can be performed on that instance. This is handy when Ruby's strftime formatting is insufficient. See
+      # the +short_ordinal+ example below.
+      #
+      # See ActiveSupport::CoreExtensions::Time::Conversions::DATE_FORMATS for the list of built-in formats, and
+      # to_formatted_s for implementation details.
+      #
+      # === Examples:
+      #   # config/initializers/time_formats.rb
+      #   ActiveSupport::CoreExtensions::Time::Conversions::DATE_FORMATS.merge!(
+      #     :month_and_year => "%B %Y",
+      #     :short_ordinal => lambda { |time| time.strftime("%B #{time.day.ordinalize}") }
+      #   )
+      #
+      # Calling it on a Time instance:
+      #
+      #   Time.now.to_s(:short_ordinal)
       module Conversions
-        def self.included(base)
+        def self.included(base) #:nodoc:
           base.class_eval do
             alias_method :to_datetime_default_s, :to_s
             alias_method :to_s, :to_formatted_s

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

 module ActiveSupport #:nodoc:
   module CoreExtensions #:nodoc:
     module Time #:nodoc:
-      # Getting times in different convenient string representations and other objects
+      # Getting times in different convenient string representations and other objects.
+      #
+      # == Adding your own time formats in to_formatted_s
+      # You can add your own time formats by merging them into the DATE_FORMATS constant. Use a string with
+      # Ruby's strftime formatting (http://ruby-doc.org/core/classes/Time.html#M000297), or
+      # pass a lambda. The lambda yields the instance to_formatted_s is called on, so that calculations
+      # can be performed on that instance. This is handy when Ruby's strftime formatting is insufficient. See
+      # the +short_ordinal+ example below.
+      #
+      # See ::Time::DATE_FORMATS for the list of built-in formats, and to_formatted_s for implementation details.
+      #
+      # === Examples:
+      #   # config/initializers/time_formats.rb
+      #   ActiveSupport::CoreExtensions::Time::Conversions::DATE_FORMATS.merge!(
+      #     :month_and_year => "%B %Y",
+      #     :short_ordinal => lambda { |time| time.strftime("%B #{time.day.ordinalize}") }
+      #   )
+      #
+      # Calling it on a Time instance:
+      #
+      #   Time.now.to_s(:short_ordinal)
       module Conversions
         DATE_FORMATS = {
           :db           => "%Y-%m-%d %H:%M:%S",
@@ -13,7 +33,7 @@ module Conversions
           :rfc822       => "%a, %d %b %Y %H:%M:%S %z"
         }
 
-        def self.included(base)
+        def self.included(base) #:nodoc:
           base.class_eval do
             alias_method :to_default_s, :to_s
             alias_method :to_s, :to_formatted_s