1 files changed, 19 insertions, 6 deletions
diff --git a/array.c b/array.c
index a4f3d984d1..d096347c43 100644
--- a/array.c
+++ b/array.c
@@ -4452,14 +4452,18 @@ ary_recycle_hash(VALUE hash)
  *
  *  Array Difference
  *
- *  Returns a new array that is a copy of the original array, removing any
- *  items that also appear in +other_ary+. The order is preserved from the
- *  original array.
+ *  Returns a new array that is a copy of the original array, removing all
+ *  instances of any item that also appear in +other_ary+. The order is preserved
+ *  from the original array.
  *
  *  It compares elements using their #hash and #eql? methods for efficiency.
  *
  *     [ 1, 1, 2, 2, 3, 3, 4, 5 ] - [ 1, 2, 4 ]  #=>  [ 3, 3, 5 ]
  *
+ *  Note that while 1 and 2 were only present once in the array argument, and
+ *  were present twice in the receiver array, all instances of each Integer are
+ *  removed in the returned array.
+ *
  *  If you need set-like behavior, see the library class Set.
  *
  *  See also Array#difference.
@@ -4499,13 +4503,22 @@ rb_ary_diff(VALUE ary1, VALUE ary2)
  *
  *  Array Difference
  *
- *  Returns a new array that is a copy of the receiver, removing any items
- *  that also appear in any of the arrays given as arguments.
- *  The order is preserved from the original array.
+ *  Returns a new array that is a copy of the original array, removing all
+ *  instances of any item that also appear in +other_ary+. The order is
+ *  preserved from the original array.
  *
  *  It compares elements using their #hash and #eql? methods for efficiency.
  *
  *     [ 1, 1, 2, 2, 3, 3, 4, 5 ].difference([ 1, 2, 4 ])     #=> [ 3, 3, 5 ]
+ *
+ *  Note that while 1 and 2 were only present once in the array argument, and
+ *  were present twice in the receiver array, all instances of each Integer are
+ *  removed in the returned array.
+ *
+ *  Multiple array arguments can be supplied and all instances of any element
+ *  in those supplied arrays that match the receiver will be removed from the
+ *  returned array.
+ *
  *     [ 1, 'c', :s, 'yep' ].difference([ 1 ], [ 'a', 'c' ])  #=> [ :s, "yep" ]
  *
  *  If you need set-like behavior, see the library class Set.