[DOC] Tweaks for Array#rotate! (#11875)

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

array.c

@@ -3186,48 +3186,34 @@ rb_ary_rotate(VALUE ary, long cnt)
 
 /*
  *  call-seq:
- *    array.rotate! -> self
+ *    rotate!(count = 1) -> self
- *    array.rotate!(count) -> self
  *
  *  Rotates +self+ in place by moving elements from one end to the other; returns +self+.
  *
- *  When no argument given, rotates the first element to the last position:
+ *  With non-negative numeric +count+,
- *
- *    a = [:foo, 'bar', 2, 'bar']
- *    a.rotate! # => ["bar", 2, "bar", :foo]
- *
- *  When given a non-negative Integer +count+,
  *  rotates +count+ elements from the beginning to the end:
  *
- *    a = [:foo, 'bar', 2]
+ *    [0, 1, 2, 3].rotate!(2)   # => [2, 3, 0, 1]
- *    a.rotate!(2)
+      [0, 1, 2, 3].rotate!(2.1) # => [2, 3, 0, 1]
- *    a # => [2, :foo, "bar"]
  *
  *  If +count+ is large, uses <tt>count % array.size</tt> as the count:
  *
- *    a = [:foo, 'bar', 2]
+ *    [0, 1, 2, 3].rotate!(21) # => [1, 2, 3, 0]
- *    a.rotate!(20)
- *    a # => [2, :foo, "bar"]
  *
- *  If +count+ is zero, returns +self+ unmodified:
+ *  If +count+ is zero, rotates no elements:
  *
- *    a = [:foo, 'bar', 2]
+ *    [0, 1, 2, 3].rotate!(0) # => [0, 1, 2, 3]
- *    a.rotate!(0)
- *    a # => [:foo, "bar", 2]
  *
- *  When given a negative Integer +count+, rotates in the opposite direction,
+ *  With a negative numeric +count+, rotates in the opposite direction,
  *  from end to beginning:
  *
- *    a = [:foo, 'bar', 2]
+ *    [0, 1, 2, 3].rotate!(-1) # => [3, 0, 1, 2]
- *    a.rotate!(-2)
- *    a # => ["bar", 2, :foo]
  *
  *  If +count+ is small (far from zero), uses <tt>count % array.size</tt> as the count:
  *
- *    a = [:foo, 'bar', 2]
+ *    [0, 1, 2, 3].rotate!(-21) # => [3, 0, 1, 2]
- *    a.rotate!(-5)
- *    a # => ["bar", 2, :foo]
  *
+ *  Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
  */
 
 static VALUE