Comply with guide for method doc: array.c (#3506)

Methods:

    any?
    all?
    one?
    none?
    sum
    shuffle!
    shuffle
    sample

array.rb

@@ -1,59 +1,56 @@
 class Array
   # call-seq:
-  #    ary.shuffle!              -> ary
-  #    ary.shuffle!(random: rng) -> ary
+  #    array.shuffle!(random: Random) -> array
   #
-  # Shuffles elements in +self+ in place.
-  #
-  #    a = [ 1, 2, 3 ]           #=> [1, 2, 3]
-  #    a.shuffle!                #=> [2, 3, 1]
-  #    a                         #=> [2, 3, 1]
-  #
-  # The optional +rng+ argument will be used as the random number generator.
+  # Shuffles the elements of +self+ in place.
+  #    a = [1, 2, 3] #=> [1, 2, 3]
+  #    a.shuffle! #=> [2, 3, 1]
   #
+  # The optional +random+ argument will be used as the random number generator:
   #    a.shuffle!(random: Random.new(1))  #=> [1, 3, 2]
   def shuffle!(random: Random)
     Primitive.rb_ary_shuffle_bang(random)
   end
 
   # call-seq:
-  #    ary.shuffle              -> new_ary
-  #    ary.shuffle(random: rng) -> new_ary
+  #    array.shuffle(random: Random) -> new_ary
   #
   # Returns a new array with elements of +self+ shuffled.
+  #    a = [1, 2, 3] #=> [1, 2, 3]
+  #    a.shuffle #=> [2, 3, 1]
   #
-  #    a = [ 1, 2, 3 ]           #=> [1, 2, 3]
-  #    a.shuffle                 #=> [2, 3, 1]
-  #    a                         #=> [1, 2, 3]
-  #
-  # The optional +rng+ argument will be used as the random number generator.
-  #
+  # The optional +random+ argument will be used as the random number generator:
   #    a.shuffle(random: Random.new(1))  #=> [1, 3, 2]
   def shuffle(random: Random)
     Primitive.rb_ary_shuffle(random)
   end
 
   # call-seq:
-  #    ary.sample                  -> obj
-  #    ary.sample(random: rng)     -> obj
-  #    ary.sample(n)               -> new_ary
-  #    ary.sample(n, random: rng)  -> new_ary
+  #    array.sample(random: Random) -> object
+  #    array.sample(n, random: Random) -> new_ary
   #
-  # Choose a random element or +n+ random elements from the array.
+  # Returns random elements from +self+.
   #
-  # 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.
+  # When no arguments are given, returns a random element from +self+:
+  #    a = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+  #    a.sample # => 3
+  #    a.sample # => 8
+  # If +self+ is empty, returns +nil+.
   #
-  # If the array is empty the first form returns +nil+ and the second form
-  # returns an empty array.
-  #
-  #    a = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ]
-  #    a.sample         #=> 7
-  #    a.sample(4)      #=> [6, 4, 2, 5]
-  #
-  # The optional +rng+ argument will be used as the random number generator.
+  # When argument +n+ is given (but not keyword argument +random+),
+  # returns a new \Array containing +n+ random elements from +self+:
+  #    a.sample(3) # => [8, 9, 2]
+  #    a.sample(6) # => [9, 6, 10, 3, 1, 4]
+  # 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]
+  # Returns a new empty \Array if +self+ is empty.
   #
+  # The optional +random+ argument will be 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]
   def sample(n = (ary = false), random: Random)