Merge branch 'master' of github.com:lifo/docrails

4 files changed, 82 insertions, 22 deletions

diff --git a/activesupport/lib/active_support/core_ext/array/access.rb b/activesupport/lib/active_support/core_ext/array/access.rb
index 44d90ef732..a8f9dddae5 100644
--- a/activesupport/lib/active_support/core_ext/array/access.rb
+++ b/activesupport/lib/active_support/core_ext/array/access.rb
@@ -1,40 +1,48 @@
 class Array
   # Returns the tail of the array from +position+.
   #
-  #   %w( a b c d ).from(0)  # => %w( a b c d )
-  #   %w( a b c d ).from(2)  # => %w( c d )
-  #   %w( a b c d ).from(10) # => %w()
-  #   %w().from(0)           # => %w()
+  #   %w( a b c d ).from(0)  # => ["a", "b", "c", "d"]
+  #   %w( a b c d ).from(2)  # => ["c", "d"]
+  #   %w( a b c d ).from(10) # => []
+  #   %w().from(0)           # => []
   def from(position)
     self[position, length] || []
   end
 
   # Returns the beginning of the array up to +position+.
   #
-  #   %w( a b c d ).to(0)  # => %w( a )
-  #   %w( a b c d ).to(2)  # => %w( a b c )
-  #   %w( a b c d ).to(10) # => %w( a b c d )
-  #   %w().to(0)           # => %w()
+  #   %w( a b c d ).to(0)  # => ["a"]
+  #   %w( a b c d ).to(2)  # => ["a", "b", "c"]
+  #   %w( a b c d ).to(10) # => ["a", "b", "c", "d"]
+  #   %w().to(0)           # => []
   def to(position)
     first position + 1
   end
 
   # Equal to <tt>self[1]</tt>.
+  #
+  #   %w( a b c d e).second # => "b"
   def second
     self[1]
   end
 
   # Equal to <tt>self[2]</tt>.
+  #
+  #   %w( a b c d e).third # => "c"
   def third
     self[2]
   end
 
   # Equal to <tt>self[3]</tt>.
+  #
+  #   %w( a b c d e).fourth # => "d"
   def fourth
     self[3]
   end
 
   # Equal to <tt>self[4]</tt>.
+  #
+  #   %w( a b c d e).fifth # => "e"
   def fifth
     self[4]
   end
diff --git a/activesupport/lib/active_support/core_ext/array/conversions.rb b/activesupport/lib/active_support/core_ext/array/conversions.rb
index d5735dd7eb..2af87d3b6b 100644
--- a/activesupport/lib/active_support/core_ext/array/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/array/conversions.rb
@@ -4,10 +4,57 @@ require 'active_support/core_ext/hash/reverse_merge'
 require 'active_support/core_ext/string/inflections'
 
 class Array
-  # Converts the array to a comma-separated sentence where the last element is joined by the connector word. Options:
-  # * <tt>:words_connector</tt> - The sign or word used to join the elements in arrays with two or more elements (default: ", ")
-  # * <tt>:two_words_connector</tt> - The sign or word used to join the elements 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 ")
+  # 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
+  #   in arrays with two or more elements (default: ", ").
+  # * <tt>:two_words_connector</tt> - The sign or word used to join the elements
+  #   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:
+  #
+  #   [].to_sentence                      # => ""
+  #   ['one'].to_sentence                 # => "one"
+  #   ['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)
 
@@ -149,6 +196,7 @@ class Array
   #       <user-id>1</user-id>
   #     </message>
   #   </messages>
+  #
   def to_xml(options = {})
     require 'active_support/builder' unless defined?(Builder)
 
diff --git a/activesupport/lib/active_support/core_ext/array/grouping.rb b/activesupport/lib/active_support/core_ext/array/grouping.rb
index ac1ae53db0..a184eb492a 100644
--- a/activesupport/lib/active_support/core_ext/array/grouping.rb
+++ b/activesupport/lib/active_support/core_ext/array/grouping.rb
@@ -2,18 +2,21 @@ class Array
   # Splits or iterates over the array in groups of size +number+,
   # padding any remaining slots with +fill_with+ unless it is +false+.
   #
-  #   %w(1 2 3 4 5 6 7).in_groups_of(3) {|group| p group}
+  #   %w(1 2 3 4 5 6 7 8 9 10).in_groups_of(3) {|group| p group}
   #   ["1", "2", "3"]
   #   ["4", "5", "6"]
-  #   ["7", nil, nil]
+  #   ["7", "8", "9"]
+  #   ["10", nil, nil]
   #
-  #   %w(1 2 3).in_groups_of(2, '&nbsp;') {|group| p group}
+  #   %w(1 2 3 4 5).in_groups_of(2, '&nbsp;') {|group| p group}
   #   ["1", "2"]
-  #   ["3", "&nbsp;"]
+  #   ["3", "4"]
+  #   ["5", "&nbsp;"]
   #
-  #   %w(1 2 3).in_groups_of(2, false) {|group| p group}
+  #   %w(1 2 3 4 5).in_groups_of(2, false) {|group| p group}
   #   ["1", "2"]
-  #   ["3"]
+  #   ["3", "4"]
+  #   ["5"]
   def in_groups_of(number, fill_with = nil)
     if fill_with == false
       collection = self
@@ -42,10 +45,10 @@ class Array
   #   ["5", "6", "7", nil]
   #   ["8", "9", "10", nil]
   #
-  #   %w(1 2 3 4 5 6 7).in_groups(3, '&nbsp;') {|group| p group}
-  #   ["1", "2", "3"]
-  #   ["4", "5", "&nbsp;"]
-  #   ["6", "7", "&nbsp;"]
+  #   %w(1 2 3 4 5 6 7 8 9 10).in_groups(3, '&nbsp;') {|group| p group}
+  #   ["1", "2", "3", "4"]
+  #   ["5", "6", "7", "&nbsp;"]
+  #   ["8", "9", "10", "&nbsp;"]
   #
   #   %w(1 2 3 4 5 6 7).in_groups(3, false) {|group| p group}
   #   ["1", "2", "3"]
diff --git a/activesupport/lib/active_support/core_ext/array/uniq_by.rb b/activesupport/lib/active_support/core_ext/array/uniq_by.rb
index c1d5a355a4..3bedfa9a61 100644
--- a/activesupport/lib/active_support/core_ext/array/uniq_by.rb
+++ b/activesupport/lib/active_support/core_ext/array/uniq_by.rb
@@ -4,6 +4,7 @@ class Array
   # Returns a unique array based on the criteria in the block.
   #
   #   [1, 2, 3, 4].uniq_by { |i| i.odd? } # => [1, 2]
+  #
   def uniq_by(&block)
     ActiveSupport::Deprecation.warn 'uniq_by is deprecated. Use Array#uniq instead', caller
     uniq(&block)