adds test coverage for edge-cases of Array.wrap, and better documentation for how it differs from Kernel#Array

1 files changed, 9 insertions, 4 deletions

diff --git a/activesupport/lib/active_support/core_ext/array/wrap.rb b/activesupport/lib/active_support/core_ext/array/wrap.rb
index e211bdeeca..09a1c2e5a1 100644
--- a/activesupport/lib/active_support/core_ext/array/wrap.rb
+++ b/activesupport/lib/active_support/core_ext/array/wrap.rb
@@ -1,9 +1,14 @@
 class Array
-  # Wraps the object in an Array unless it's an Array.  Converts the
-  # object to an Array using #to_ary if it implements that.
+  # <tt>Array.wrap</tt> is like <tt>Kernel#Array</tt> except:
   #
-  # It differs with Array() in that it does not call +to_a+ on
-  # the argument:
+  # * If the argument responds to +to_ary+ the method is invoked. <tt>Kernel#Array</tt>
+  # moves on to try +to_a+ if the returned value is +nil+, but <tt>Arraw.wrap</tt> returns
+  # such a +nil+ right away.
+  # * If the returned value from +to_ary+ is neither +nil+ nor an +Array+ object, <tt>Kernel#Array</tt>
+  # raises an exception, while <tt>Array.wrap</tt> does not, it just returns the value.
+  # * It does not call +to_a+ on the argument, though special-cases +nil+ to return an empty array.
+  #
+  # The last point is particularly worth comparing for some enumerables:
   #
   #   Array(:foo => :bar)      # => [[:foo, :bar]]
   #   Array.wrap(:foo => :bar) # => [{:foo => :bar}]