1 files changed, 23 insertions, 2 deletions
diff --git a/activesupport/lib/active_support/core_ext/date_time/conversions.rb b/activesupport/lib/active_support/core_ext/date_time/conversions.rb
index 8ea8679b42..2ee663ac93 100644
--- a/activesupport/lib/active_support/core_ext/date_time/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/date_time/conversions.rb
@@ -1,9 +1,30 @@
 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