[DOC] Tweaks for Array#sample (#11876)

Merged-By: peterzhu2118 <peter@peterzhu.ca>

array.rb

@@ -73,35 +73,52 @@ class Array
   end
 
   # call-seq:
-  #    array.sample(random: Random) -> object
-  #    array.sample(n, random: Random) -> new_ary
+  #   sample(random: Random) -> object
+  #   sample(count, random: Random) -> new_ary
   #
-  # Returns random elements from +self+.
+  # Returns random elements from +self+,
+  # as selected by the object given by keyword argument +random+.
   #
-  # When no arguments are given, returns a random element from +self+:
-  #    a = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+  # With no argument +count+ given, returns one random element from +self+:
+  #
+  #    a = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
   #    a.sample # => 3
   #    a.sample # => 8
-  # If +self+ is empty, returns +nil+.
   #
-  # When argument +n+ is given, returns a new +Array+ containing +n+ random
-  # elements from +self+:
+  # Returns +nil+ if +self+ is empty:
+  #
+  #    [].sample # => nil
+  #
+  #
+  # With non-negative numeric argument +count+ given,
+  # returns a new array containing +count+ random elements from +self+:
+  #
   #    a.sample(3) # => [8, 9, 2]
-  #    a.sample(6) # => [9, 6, 10, 3, 1, 4]
+  #    a.sample(6) # => [9, 6, 0, 3, 1, 4]
+  #
+  # The order of the result array is unrelated to the order of +self+.
+  #
+  # Returns a new empty +Array+ if +self+ is empty:
+  #
+  #   [].sample(4) # => []
+  #
+  # May return duplicates in +self+:
+  #
+  #    a = [1, 1, 1, 2, 2, 3]
+  #    a.sample(a.size) # => [1, 1, 3, 2, 1, 2]
+  #
   # Returns no more than <tt>a.size</tt> elements
   # (because no new duplicates are introduced):
-  #    a.sample(a.size * 2) # => [6, 4, 1, 8, 5, 9, 10, 2, 3, 7]
-  # But +self+ may contain duplicates:
-  #    a = [1, 1, 1, 2, 2, 3]
-  #    a.sample(a.size * 2) # => [1, 1, 3, 2, 1, 2]
-  # The argument +n+ must be a non-negative numeric value.
-  # The order of the result array is unrelated to the order of +self+.
-  # Returns a new empty +Array+ if +self+ is empty.
   #
-  # The optional +random+ argument will be used as the random number generator:
+  #    a.sample(50) # => [6, 4, 1, 8, 5, 9, 0, 2, 3, 7]
+  #
+  # The object given with keyword argument +random+ is used as the random number generator:
+  #
   #    a = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
   #    a.sample(random: Random.new(1))     #=> 6
   #    a.sample(4, random: Random.new(1))  #=> [6, 10, 9, 2]
+  #
+  # Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
   def sample(n = (ary = false), random: Random)
     if Primitive.mandatory_only?
       # Primitive.cexpr! %{ rb_ary_sample(self, rb_cRandom, Qfalse, Qfalse) }