Simplify to_formatted_s docs. Closes #10747 [Jeremy Kemper]

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

3 files changed, 38 insertions, 74 deletions

diff --git a/activesupport/lib/active_support/core_ext/date/conversions.rb b/activesupport/lib/active_support/core_ext/date/conversions.rb
index e06ca3ada5..d2d9699d01 100644
--- a/activesupport/lib/active_support/core_ext/date/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/date/conversions.rb
@@ -1,27 +1,7 @@
 module ActiveSupport #:nodoc:
   module CoreExtensions #:nodoc:
     module Date #:nodoc:
-      # 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)
+      # Converting dates to formatted strings, times, and datetimes.
       module Conversions
         DATE_FORMATS = {
           :short        => "%e %b",
@@ -47,10 +27,9 @@ module ActiveSupport #: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.
+        # Convert to a formatted string. See DATE_FORMATS for predefined formats.
         #
-        # This method is also aliased as <tt>to_s</tt>.
+        # This method is aliased to <tt>to_s</tt>.
         #
         # ==== Examples:
         #   date = Date.new(2007, 11, 10)       # => Sat, 10 Nov 2007
@@ -62,6 +41,15 @@ module ActiveSupport #:nodoc:
         #   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"
+        #
+        # == Adding your own time formats to to_formatted_s
+        # You can add your own formats to the Date::DATE_FORMATS hash.
+        # Use the format name as the hash key and either a strftime string
+        # or Proc instance that takes a date argument as the value.
+        #
+        #   # config/initializers/time_formats.rb
+        #   Date::DATE_FORMATS[:month_and_year] = "%B %Y"
+        #   Date::DATE_FORMATS[:short_ordinal] = lambda { |date| date.strftime("%B #{date.day.ordinalize}") }
         def to_formatted_s(format = :default)
           if formatter = DATE_FORMATS[format]
             if formatter.respond_to?(:call)
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 2ee663ac93..f9645fd3cf 100644
--- a/activesupport/lib/active_support/core_ext/date_time/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/date_time/conversions.rb
@@ -1,28 +1,7 @@
 module ActiveSupport #:nodoc:
   module CoreExtensions #:nodoc:
     module DateTime #:nodoc:
-      # 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)
+      # Converting datetimes to formatted strings, dates, and times.
       module Conversions
         def self.included(base) #:nodoc:
           base.class_eval do
@@ -36,11 +15,10 @@ module ActiveSupport #:nodoc:
             remove_method :to_time if base.instance_methods.include?(:to_time)
           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.
+
+        # Convert to a formatted string. See Time::DATE_FORMATS for predefined formats.
         # 
-        # This method is also aliased as <tt>to_s</tt>.
+        # This method is aliased to <tt>to_s</tt>.
         # 
         # === Examples:
         #   datetime = DateTime.civil(2007, 12, 4, 0, 0, 0, 0)   # => Tue, 04 Dec 2007 00:00:00 +0000
@@ -52,6 +30,16 @@ module ActiveSupport #:nodoc:
         #   datetime.to_formatted_s(:long)          # => "December 04, 2007 00:00"
         #   datetime.to_formatted_s(:long_ordinal)  # => "December 4th, 2007 00:00"
         #   datetime.to_formatted_s(:rfc822)        # => "Tue, 04 Dec 2007 00:00:00 +0000"
+        #
+        # == Adding your own datetime formats to to_formatted_s
+        # DateTime formats are shared with Time. You can add your own to the
+        # Time::DATE_FORMATS hash. Use the format name as the hash key and
+        # either a strftime string or Proc instance that takes a time or
+        # datetime argument as the value.
+        #
+        #   # config/initializers/time_formats.rb
+        #   Time::DATE_FORMATS[:month_and_year] = "%B %Y"
+        #   Time::DATE_FORMATS[:short_ordinal] = lambda { |time| time.strftime("%B #{time.day.ordinalize}") }
         def to_formatted_s(format = :default)
           if formatter = ::Time::DATE_FORMATS[format]
             if formatter.respond_to?(:call)
diff --git a/activesupport/lib/active_support/core_ext/time/conversions.rb b/activesupport/lib/active_support/core_ext/time/conversions.rb
index 13f41fffbd..ffc9b05a8c 100644
--- a/activesupport/lib/active_support/core_ext/time/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/time/conversions.rb
@@ -1,27 +1,7 @@
 module ActiveSupport #:nodoc:
   module CoreExtensions #:nodoc:
     module Time #:nodoc:
-      # 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)
+      # Converting times to formatted strings, dates, and datetimes.
       module Conversions
         DATE_FORMATS = {
           :db           => "%Y-%m-%d %H:%M:%S",
@@ -40,10 +20,9 @@ module ActiveSupport #: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.
+        # Convert to a formatted string. See DATE_FORMATS for builtin formats.
         #
-        # This method is also aliased as <tt>to_s</tt>.
+        # This method is aliased to <tt>to_s</tt>.
         #
         # ==== Examples:
         #   time = Time.now                     # => Thu Jan 18 06:10:17 CST 2007
@@ -56,6 +35,15 @@ module ActiveSupport #:nodoc:
         #   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"
+        #
+        # == Adding your own time formats to to_formatted_s
+        # You can add your own formats to the Time::DATE_FORMATS hash.
+        # Use the format name as the hash key and either a strftime string
+        # or Proc instance that takes a time argument as the value.
+        #
+        #   # config/initializers/time_formats.rb
+        #   Time::DATE_FORMATS[:month_and_year] = "%B %Y"
+        #   Time::DATE_FORMATS[:short_ordinal] = lambda { |time| time.strftime("%B #{time.day.ordinalize}") }
         def to_formatted_s(format = :default)
           if formatter = DATE_FORMATS[format]
             if formatter.respond_to?(:call)