1 files changed, 5 insertions, 3 deletions
diff --git a/array.c b/array.c
index 52981a2b4f..b9b60c8736 100644
--- a/array.c
+++ b/array.c
@@ -3526,9 +3526,11 @@ rb_ary_shuffle(VALUE ary)
  *     array.sample        -> obj
  *     array.sample(n)     -> an_array
  *
- *  Choose a random element, or the random +n+ elements, from the array.
- *  If the array is empty, the first form returns <code>nil</code>, and the
- *  second form returns an empty array.
+ *  Choose a random element or +n+ random elements from the array. The elements
+ *  are chosen by using random and unique indices into the array in order to
+ *  ensure that an element doesn't repeat itself unless the array already
+ *  contained duplicate elements. If the array is empty the first form returns
+ *  <code>nil</code> and the second form returns an empty array.
  *
  */