* array.c: Harmonize documentation, in particular regarding:

    - methods returning enumerators
    - array methods and argument naming (array -> ary, an_array -> new_ary)
    - minor improvements, typo fixed and styling issues

  Other documentation errors fixed:
    - return value was self instead of a new array (or vice-versa) for
      Array#{pop,shift,permutation,repeated_permutation,keep_if}
    - Array#rindex was missing the form with a block.

* dir.c: ditto.

* enum.c: ditto. Modified Enumerable#reverse_each' documentation to clarify
  that #each will be finish before any element is yielded.

* error.c: ditto.

* gc.c: ditto.

* hash.c: ditto.

* io.c: ditto. IO#{codepoints,each_codepoint} fixed as per [ruby-core:23948]

* numeric.c: ditto.

* range.c: ditto.

* string.c: ditto.

* struct.c: ditto.

* vm_eval.c: ditto.

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

1 files changed, 14 insertions, 6 deletions

diff --git a/numeric.c b/numeric.c
index 31b3756d25..808c364528 100644
--- a/numeric.c
+++ b/numeric.c
@@ -494,7 +494,7 @@ num_zero_p(VALUE num)
  *  call-seq:
  *     num.nonzero?  ->  self or nil
  *
- *  Returns <i>self</i> if <i>num</i> is not zero, <code>nil</code>
+ *  Returns +self+ if <i>num</i> is not zero, <code>nil</code>
  *  otherwise. This behavior is useful when chaining comparisons:
  *
  *     a = %w( z Bb bB bb BB a aA Aa AA A )
@@ -1234,7 +1234,7 @@ flo_eql(VALUE x, VALUE y)
  * call-seq:
  *   flt.to_f  ->  self
  *
- * As <code>flt</code> is already a float, returns <i>self</i>.
+ * As <code>flt</code> is already a float, returns +self+.
  */
 
 static VALUE
@@ -1596,7 +1596,7 @@ ruby_float_step(VALUE from, VALUE to, VALUE step, int excl)
 /*
  *  call-seq:
  *     num.step(limit[, step]) {|i| block }  ->  self
- *     num.step(limit[, step])               ->  enumerator
+ *     num.step(limit[, step])               ->  an_enumerator
  *
  *  Invokes <em>block</em> with the sequence of numbers starting at
  *  <i>num</i>, incremented by <i>step</i> (default 1) on each
@@ -1612,6 +1612,8 @@ ruby_float_step(VALUE from, VALUE to, VALUE step, int excl)
  *  the counter against <i>limit</i>, and increments itself using the
  *  <code>+</code> operator.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     1.step(10, 2) { |i| print i, " " }
  *     Math::E.step(Math::PI, 0.2) { |f| print f, " " }
  *
@@ -3018,11 +3020,13 @@ fix_size(VALUE fix)
 /*
  *  call-seq:
  *     int.upto(limit) {|i| block }  ->  self
- *     int.upto(limit)               ->  enumerator
+ *     int.upto(limit)               ->  an_enumerator
  *
  *  Iterates <em>block</em>, passing in integer values from <i>int</i>
  *  up to and including <i>limit</i>.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     5.upto(10) { |i| print i, " " }
  *
  *  <em>produces:</em>
@@ -3057,11 +3061,13 @@ int_upto(VALUE from, VALUE to)
 /*
  *  call-seq:
  *     int.downto(limit) {|i| block }  ->  self
- *     int.downto(limit)               ->  enumerator
+ *     int.downto(limit)               ->  an_enumerator
  *
  *  Iterates <em>block</em>, passing decreasing values from <i>int</i>
  *  down to and including <i>limit</i>.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     5.downto(1) { |n| print n, ".. " }
  *     print "  Liftoff!\n"
  *
@@ -3097,11 +3103,13 @@ int_downto(VALUE from, VALUE to)
 /*
  *  call-seq:
  *     int.times {|i| block }  ->  self
- *     int.times               ->  enumerator
+ *     int.times               ->  an_enumerator
  *
  *  Iterates block <i>int</i> times, passing in values from zero to
  *  <i>int</i> - 1.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     5.times do |i|
  *       print i, " "
  *     end