Improve Array#sample with random documentation

* array.c (rb_ary_sample): Adds examples for the use of the
  optional parameter random for Array#sample and unifies the style
  with the documentation of Array#shuffle.

[Fix GH-1825]

From: Alberto Almagro <alberto.almagro@rakuten.com>

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@62553 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 5 insertions, 2 deletions

diff --git a/array.c b/array.c
index a821575676..f97447f7ea 100644
--- a/array.c
+++ b/array.c
@@ -4868,11 +4868,14 @@ rb_ary_shuffle(int argc, VALUE *argv, VALUE ary)
  *  If the array is empty the first form returns +nil+ and the second form
  *  returns an empty array.
  *
- *  The optional +rng+ argument will be used as the random number generator.
- *
  *     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.
+ *
+ *     a.sample(random: Random.new(1))     #=> 6
+ *     a.sample(4, random: Random.new(1))  #=> [6, 10, 9, 2]
  */