Merge pull request #19128 from davydovanton/update-doc-range-to-s

[ci skip] Update documentation for Range#to_formatted_s

1 files changed, 17 insertions, 2 deletions

diff --git a/activesupport/lib/active_support/core_ext/range/conversions.rb b/activesupport/lib/active_support/core_ext/range/conversions.rb
index b1a12781f3..83eced50bf 100644
--- a/activesupport/lib/active_support/core_ext/range/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/range/conversions.rb
@@ -3,9 +3,24 @@ class Range
     :db => Proc.new { |start, stop| "BETWEEN '#{start.to_s(:db)}' AND '#{stop.to_s(:db)}'" }
   }
 
-  # Gives a human readable format of the range.
+  # Convert range to a formatted string. See RANGE_FORMATS for predefined formats.
   #
-  #   (1..100).to_formatted_s # => "1..100"
+  # This method is aliased to <tt>to_s</tt>.
+  #
+  #   range = (1..100)           # => 1..100
+  #
+  #   range.to_formatted_s       # => "1..100"
+  #   range.to_s                 # => "1..100"
+  #
+  #   range.to_formatted_s(:db)  # => "BETWEEN '1' AND '100'"
+  #   range.to_s(:db)            # => "BETWEEN '1' AND '100'"
+  #
+  # == Adding your own range formats to to_formatted_s
+  # You can add your own formats to the Range::RANGE_FORMATS hash.
+  # Use the format name as the hash key and a Proc instance.
+  #
+  #   # config/initializers/range_formats.rb
+  #   Range::RANGE_FORMATS[:short] = ->(start, stop) { "Between #{start.to_s(:db)} and #{stop.to_s(:db)}" }
   def to_formatted_s(format = :default)
     if formatter = RANGE_FORMATS[format]
       formatter.call(first, last)