2 files changed, 12 insertions, 0 deletions
diff --git a/ChangeLog b/ChangeLog
index df161fb373..155017382c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+Sat May 24 22:37:20 2014  SHIBATA Hiroshi  <shibata.hiroshi@gmail.com>
+
+	* array.c: [DOC] Add more documents to shuffle! and shuffle.
+	  Contributed by @JuanitoFatas [ci skip][fix GH-612]
+
 Sat May 24 22:28:55 2014  SHIBATA Hiroshi  <shibata.hiroshi@gmail.com>
 
 	* test/lib/minitest/.document: removed unused configuration.
diff --git a/array.c b/array.c
index 915cb566d1..ca3b8a4769 100644
--- a/array.c
+++ b/array.c
@@ -4459,7 +4459,13 @@ static ID id_random;
  *
  *  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.
+ *
+ *     a.shuffle!(random: Random.new(1))  #=> [1, 3, 2]
  */
 
 static VALUE
@@ -4506,6 +4512,7 @@ rb_ary_shuffle_bang(int argc, VALUE *argv, VALUE ary)
  *
  *     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.
  *