Documentation for Array#sample

1 files changed, 7 insertions, 0 deletions

diff --git a/activesupport/lib/active_support/core_ext/array/random_access.rb b/activesupport/lib/active_support/core_ext/array/random_access.rb
index 7a4836cecd..edac7278bc 100644
--- a/activesupport/lib/active_support/core_ext/array/random_access.rb
+++ b/activesupport/lib/active_support/core_ext/array/random_access.rb
@@ -1,5 +1,12 @@
 class Array
   # Backport of Array#sample based on Marc-Andre Lafortune's http://github.com/marcandre/backports/
+  # Returns a random element or +n+ random elements from the array. 
+  # If the array is empty and +n+ is nil, returns <tt>nil</tt>. if +n+ is passed, returns <tt>[]</tt>.
+  # 
+  #   [1,2,3,4,5,6].sample    # => 4 
+  #   [1,2,3,4,5,6].sample(3) # => [2, 4, 5] 
+  #              [].sample    # => nil
+  #              [].sample(3) # => []
   def sample(n=nil)
     return self[Kernel.rand(size)] if n.nil?
     n = n.to_int