add :locale option to Array#to_sentence documentation [ci skip]

1 files changed, 27 insertions, 0 deletions

diff --git a/activesupport/lib/active_support/core_ext/array/conversions.rb b/activesupport/lib/active_support/core_ext/array/conversions.rb
index d794713ed5..74b5c73664 100644
--- a/activesupport/lib/active_support/core_ext/array/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/array/conversions.rb
@@ -7,6 +7,10 @@ class Array
   # Converts the array to a comma-separated sentence where the last element is
   # joined by the connector word.
   #
+  # You can pass the following options to change the default behaviour. If you
+  # pass an option key that doesn't exist in the next list, it will raise an
+  # "Unknow key" error.
+  #
   # Options:
   #
   # * <tt>:words_connector</tt> - The sign or word used to join the elements
@@ -15,6 +19,9 @@ class Array
   #   in arrays with two elements (default: " and ").
   # * <tt>:last_word_connector</tt> - The sign or word used to join the last element
   #   in arrays with three or more elements (default: ", and ").
+  # * <tt>:locale</tt> - If +i18n+ is available, you can set a locale and use
+  #   the connector options defined on the 'support.array' namespace in the
+  #   corresponding dictionary file.
   #
   # Examples:
   #
@@ -23,11 +30,31 @@ class Array
   #   ['one', 'two'].to_sentence          # => "one and two"
   #   ['one', 'two', 'three'].to_sentence # => "one, two, and three"
   #
+  #   ['one', 'two'].to_sentence(passing: 'invalid option')
+  #   # => ArgumentError: Unknown key :passing
+  #
   #   ['one', 'two'].to_sentence(two_words_connector: '-')
   #   # => "one-two"
   #
   #   ['one', 'two', 'three'].to_sentence(words_connector: ' or ', last_word_connector: ' or at least ')
   #   # => "one or two or at least three"
+  #
+  # Examples using <tt>:locale</tt> option:
+  #
+  #   # With the next locale dictionary:
+  #   # 
+  #   #   es:
+  #   #     support:
+  #   #       array:
+  #   #         words_connector: " o "
+  #   #         two_words_connector: " y "
+  #   #         last_word_connector: " o al menos "
+  #
+  #   ['uno', 'dos'].to_sentence(locale: :es)
+  #   # => "uno y dos"
+  #
+  #   ['uno', 'dos', 'tres'].to_sentence(locale: :es)
+  #   # => "uno o dos o al menos tres"
   def to_sentence(options = {})
     options.assert_valid_keys(:words_connector, :two_words_connector, :last_word_connector, :locale)