* 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

dir.c

@@ -592,10 +592,13 @@ dir_read(VALUE dir)
 /*
  *  call-seq:
  *     dir.each { |filename| block }  => dir
+ *     dir.each                       => an_enumerator
  *
  *  Calls the block once for each entry in this directory, passing the
  *  filename of each entry as a parameter to the block.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     d = Dir.new("testdir")
  *     d.each  {|x| puts "Got #{x}" }
  *
@@ -1820,10 +1823,13 @@ dir_open_dir(int argc, VALUE *argv)
 /*
  *  call-seq:
  *     Dir.foreach( dirname ) {| filename | block }  => nil
+ *     Dir.foreach( dirname )                        => an_enumerator
  *
  *  Calls the block once for each entry in the named directory, passing
  *  the filename of each entry as a parameter to the block.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     Dir.foreach("testdir") {|x| puts "Got #{x}" }
  *
  *  <em>produces:</em>

enum.c

@@ -181,11 +181,15 @@ find_i(VALUE i, VALUE *memo, int argc, VALUE *argv)
  *  call-seq:
  *     enum.detect(ifnone = nil) {| obj | block }  => obj or nil
  *     enum.find(ifnone = nil)   {| obj | block }  => obj or nil
+ *     enum.detect(ifnone = nil)                   => an_enumerator
+ *     enum.find(ifnone = nil)                     => an_enumerator
  *
  *  Passes each entry in <i>enum</i> to <em>block</em>. Returns the
- *  first for which <em>block</em> is not <code>false</code>.  If no
+ *  first for which <em>block</em> is not false.  If no
  *  object matches, calls <i>ifnone</i> and returns its result when it
- *  is specified, or returns <code>nil</code>
+ *  is specified, or returns <code>nil</code> otherwise.
+ *
+ *  If no block is given, an enumerator is returned instead.
  *
  *     (1..10).detect  {|i| i % 5 == 0 and i % 7 == 0 }   #=> nil
  *     (1..100).detect {|i| i % 5 == 0 and i % 7 == 0 }   #=> 35
@@ -242,12 +246,15 @@ find_index_iter_i(VALUE i, VALUE memop, int argc, VALUE *argv)
  *  call-seq:
  *     enum.find_index(value)            => int or nil
  *     enum.find_index {| obj | block }  => int or nil
+ *     enum.find_index                   => an_enumerator
  *
  *  Compares each entry in <i>enum</i> with <em>value</em> or passes
  *  to <em>block</em>.  Returns the index for the first for which the
  *  evaluated value is non-false.  If no object matches, returns
  *  <code>nil</code>
  *
+ *  If neither block nor argument is given, an enumerator is returned instead.
+ *
  *     (1..10).find_index  {|i| i % 5 == 0 and i % 7 == 0 }   #=> nil
  *     (1..100).find_index {|i| i % 5 == 0 and i % 7 == 0 }   #=> 34
  *     (1..100).find_index(50)                                #=> 49
@@ -293,11 +300,16 @@ find_all_i(VALUE i, VALUE ary, int argc, VALUE *argv)
  *  call-seq:
  *     enum.find_all {| obj | block }  => array
  *     enum.select   {| obj | block }  => array
+ *     enum.find_all                   => an_enumerator
+ *     enum.select                     => an_enumerator
  *
  *  Returns an array containing all elements of <i>enum</i> for which
  *  <em>block</em> is not <code>false</code> (see also
  *  <code>Enumerable#reject</code>).
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
+ *
  *     (1..10).find_all {|i|  i % 3 == 0 }   #=> [3, 6, 9]
  *
  */
@@ -329,10 +341,13 @@ reject_i(VALUE i, VALUE ary, int argc, VALUE *argv)
 /*
  *  call-seq:
  *     enum.reject {| obj | block }  => array
+ *     enum.reject                   => an_enumerator
  *
  *  Returns an array for all elements of <i>enum</i> for which
  *  <em>block</em> is false (see also <code>Enumerable#find_all</code>).
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     (1..10).reject {|i|  i % 3 == 0 }   #=> [1, 2, 4, 5, 7, 8, 10]
  *
  */
@@ -371,10 +386,14 @@ collect_all(VALUE i, VALUE ary, int argc, VALUE *argv)
  *  call-seq:
  *     enum.collect {| obj | block }  => array
  *     enum.map     {| obj | block }  => array
+ *     enum.collect                   => an_enumerator
+ *     enum.map                       => an_enumerator
  *
  *  Returns a new array with the results of running <em>block</em> once
  *  for every element in <i>enum</i>.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     (1..4).collect {|i| i*i }   #=> [1, 4, 9, 16]
  *     (1..4).collect { "cat"  }   #=> ["cat", "cat", "cat", "cat"]
  *
@@ -414,10 +433,14 @@ flat_map_i(VALUE i, VALUE ary, int argc, VALUE *argv)
  *  call-seq:
  *     enum.flat_map       {| obj | block }  => array
  *     enum.collect_concat {| obj | block }  => array
+ *     enum.flat_map                         => an_enumerator
+ *     enum.collect_concat                   => an_enumerator
  *
  *  Returns a new array with the concatenated results of running
  *  <em>block</em> once for every element in <i>enum</i>.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     [[1,2],[3,4]].flat_map {|i| i }   #=> [1, 2, 3, 4]
  *
  */
@@ -581,11 +604,14 @@ partition_i(VALUE i, VALUE *ary, int argc, VALUE *argv)
 /*
  *  call-seq:
  *     enum.partition {| obj | block }  => [ true_array, false_array ]
+ *     enum.partition                   => an_enumerator
  *
  *  Returns two arrays, the first containing the elements of
  *  <i>enum</i> for which the block evaluates to true, the second
  *  containing the rest.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     (1..6).partition {|i| (i&1).zero?}   #=> [[2, 4, 6], [1, 3, 5]]
  *
  */
@@ -627,11 +653,14 @@ group_by_i(VALUE i, VALUE hash, int argc, VALUE *argv)
 /*
  *  call-seq:
  *     enum.group_by {| obj | block }  => a_hash
+ *     enum.group_by                   => an_enumerator
  *
  *  Returns a hash, which keys are evaluated result from the
  *  block, and values are arrays of elements in <i>enum</i>
  *  corresponding to the key.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     (1..6).group_by {|i| i%3}   #=> {0=>[3, 6], 1=>[1, 4], 2=>[2, 5]}
  *
  */
@@ -764,10 +793,13 @@ sort_by_cmp(const void *ap, const void *bp, void *data)
 /*
  *  call-seq:
  *     enum.sort_by {| obj | block }    => array
+ *     enum.sort_by                     => an_enumerator
  *
  *  Sorts <i>enum</i> using a set of keys generated by mapping the
  *  values in <i>enum</i> through the given block.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     %w{ apple pear fig }.sort_by {|word| word.length}
  *                   #=> ["fig", "pear", "apple"]
  *
@@ -777,11 +809,10 @@ sort_by_cmp(const void *ap, const void *bp, void *data)
  *  the keysets are simple
  *
  *     require 'benchmark'
- *     include Benchmark
  *
  *     a = (1..100000).map {rand(100000)}
  *
- *     bm(10) do |b|
+ *     Benchmark.bm(10) do |b|
  *       b.report("Sort")    { a.sort }
  *       b.report("Sort by") { a.sort_by {|a| a} }
  *     end
@@ -1335,10 +1366,13 @@ min_by_i(VALUE i, VALUE *memo, int argc, VALUE *argv)
 /*
  *  call-seq:
  *     enum.min_by {|obj| block }   => obj
+ *     enum.min_by                  => an_enumerator
  *
  *  Returns the object in <i>enum</i> that gives the minimum
  *  value from the given block.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     a = %w(albatross dog horse)
  *     a.min_by {|x| x.length }   #=> "dog"
  */
@@ -1378,10 +1412,13 @@ max_by_i(VALUE i, VALUE *memo, int argc, VALUE *argv)
 /*
  *  call-seq:
  *     enum.max_by {|obj| block }   => obj
+ *     enum.max_by                  => an_enumerator
  *
  *  Returns the object in <i>enum</i> that gives the maximum
  *  value from the given block.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     a = %w(albatross dog horse)
  *     a.max_by {|x| x.length }   #=> "albatross"
  */
@@ -1472,11 +1509,14 @@ minmax_by_i(VALUE i, VALUE _memo, int argc, VALUE *argv)
 /*
  *  call-seq:
  *     enum.minmax_by {|obj| block }   => [min, max]
+ *     enum.minmax_by                  => an_enumerator
  *
  *  Returns two elements array array containing the objects in
  *  <i>enum</i> that gives the minimum and maximum values respectively
  *  from the given block.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     a = %w(albatross dog horse)
  *     a.minmax_by {|x| x.length }   #=> ["dog", "albatross"]
  */
@@ -1544,12 +1584,15 @@ each_with_index_i(VALUE i, VALUE memo, int argc, VALUE *argv)
 
 /*
  *  call-seq:
- *     enum.each_with_index {|obj, i| block }  -> enum
+ *     enum.each_with_index(*args) {|obj, i| block }  -> enum
+ *     enum.each_with_index(*args)                    -> an_enumerator
  *
  *  Calls <em>block</em> with two arguments, the item and its index,
  *  for each item in <i>enum</i>.  Given arguments are passed through
  *  to #each().
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     hash = Hash.new
  *     %w(cat dog wombat).each_with_index {|item, index|
  *       hash[item] = index
@@ -1573,9 +1616,13 @@ enum_each_with_index(int argc, VALUE *argv, VALUE obj)
 
 /*
  *  call-seq:
- *     enum.reverse_each {|item| block }
+ *     enum.reverse_each(*args) {|item| block }  -> enum
+ *     enum.reverse_each(*args)                  -> an_enumerator
+ *
+ *  Builds a temporary array and traverses that array in reverse order.
+ *
+ *  If no block is given, an enumerator is returned instead.
  *
- *  Traverses <i>enum</i> in reverse order.
  */
 
 static VALUE
@@ -1607,11 +1654,14 @@ each_val_i(VALUE i, VALUE p, int argc, VALUE *argv)
 /*
  *  call-seq:
  *     enum.each_entry {|obj| block}  => enum
+ *     enum.each_entry                => an_enumerator
  *
- *  Calls <i>block</i> once for each element in <i>self</i>, passing that
+ *  Calls <i>block</i> once for each element in +self+, passing that
  *  element as a parameter, converting multiple values from yield to an
  *  array.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     class Foo
  *       include Enumerable
  *       def each
@@ -1654,8 +1704,8 @@ each_slice_i(VALUE i, VALUE *memo, int argc, VALUE *argv)
 
 /*
  *  call-seq:
- *    e.each_slice(n) {...}
+ *    enum.each_slice(n) {...} -> nil
- *    e.each_slice(n)
+ *    enum.each_slice(n)       -> an_enumerator
  *
  *  Iterates the given block for each slice of <n> elements.  If no
  *  block is given, returns an enumerator.
@@ -1708,8 +1758,8 @@ each_cons_i(VALUE i, VALUE *memo, int argc, VALUE *argv)
 
 /*
  *  call-seq:
- *    each_cons(n) {...}
+ *    enum.each_cons(n) {...}  -> nil
- *    each_cons(n)
+ *    enum.each_cons(n)        -> an_enumerator
  *
  *  Iterates the given block for each array of consecutive <n>
  *  elements.  If no block is given, returns an enumerator.
@@ -1752,8 +1802,8 @@ each_with_object_i(VALUE i, VALUE memo, int argc, VALUE *argv)
 
 /*
  *  call-seq:
- *    each_with_object(obj) {|(*args), memo_obj| ... }
+ *    enum.each_with_object(obj) {|(*args), memo_obj| ... } -> obj
- *    each_with_object(obj)
+ *    enum.each_with_object(obj)                            -> an_enumerator
  *
  *  Iterates the given block for each element with an arbitrary
  *  object given, and returns the initially given object.
@@ -1854,7 +1904,7 @@ zip_i(VALUE val, NODE *memo, int argc, VALUE *argv)
 
 /*
  *  call-seq:
- *     enum.zip(arg, ...)                   => enumerator
+ *     enum.zip(arg, ...)                   => an_enumerator
  *     enum.zip(arg, ...) {|arr| block }    => nil
  *
  *  Takes one element from <i>enum</i> and merges corresponding
@@ -1958,10 +2008,13 @@ take_while_i(VALUE i, VALUE *ary, int argc, VALUE *argv)
 /*
  *  call-seq:
  *     enum.take_while {|arr| block }   => array
+ *     enum.take_while                  => an_enumerator
  *
- *  Passes elements to the block until the block returns nil or false,
+ *  Passes elements to the block until the block returns +nil+ or +false+,
  *  then stops iterating and returns an array of all prior elements.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     a = [1, 2, 3, 4, 5, 0]
  *     a.take_while {|i| i < 3 }   # => [1, 2]
  *
@@ -2036,11 +2089,14 @@ drop_while_i(VALUE i, VALUE *args, int argc, VALUE *argv)
 /*
  *  call-seq:
  *     enum.drop_while {|arr| block }   => array
+ *     enum.drop_while                  => an_enumerator
  *
  *  Drops elements up to, but not including, the first element for
- *  which the block returns nil or false and returns an array
+ *  which the block returns +nil+ or +false+ and returns an array
  *  containing the remaining elements.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     a = [1, 2, 3, 4, 5, 0]
  *     a.drop_while {|i| i < 3 }   # => [3, 4, 5, 0]
  *
@@ -2070,17 +2126,19 @@ cycle_i(VALUE i, VALUE ary, int argc, VALUE *argv)
 
 /*
  *  call-seq:
- *     enum.cycle {|obj| block }
+ *     enum.cycle(n=nil) {|obj| block }  -> nil
- *     enum.cycle(n) {|obj| block }
+ *     enum.cycle(n=nil)                 -> an_enumerator
  *
  *  Calls <i>block</i> for each element of <i>enum</i> repeatedly _n_
- *  times or forever if none or nil is given.  If a non-positive
+ *  times or forever if none or +nil+ is given.  If a non-positive
  *  number is given or the collection is empty, does nothing.  Returns
- *  nil if the loop has finished without getting interrupted.
+ *  +nil+ if the loop has finished without getting interrupted.
  *
  *  Enumerable#cycle saves elements in an internal array so changes
  *  to <i>enum</i> after the first pass have no effect.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     a = ["a", "b", "c"]
  *     a.cycle {|x| puts x }  # print, a, b, c, a, b, c,.. forever.
  *     a.cycle(2) {|x| puts x }  # print, a, b, c, a, b, c.
@@ -2114,7 +2172,7 @@ enum_cycle(int argc, VALUE *argv, VALUE obj)
             rb_yield(RARRAY_PTR(ary)[i]);
         }
     }
-    return Qnil;		/* not reached */
+    return Qnil;
 }
 
 struct chunk_arg {
@@ -2199,8 +2257,8 @@ chunk_i(VALUE yielder, VALUE enumerator, int argc, VALUE *argv)
 
 /*
  *  call-seq:
- *     enum.chunk {|elt| ... } => enumerator
+ *     enum.chunk {|elt| ... } => an_enumerator
- *     enum.chunk(initial_state) {|elt, state| ... } => enumerator
+ *     enum.chunk(initial_state) {|elt, state| ... } => an_enumerator
  *
  *  Creates an enumerator for each chunked elements.
  *  The consecutive elements which have same block value are chunked.
@@ -2374,9 +2432,9 @@ slicebefore_i(VALUE yielder, VALUE enumerator, int argc, VALUE *argv)
 
 /*
  *  call-seq:
- *     enum.slice_before(pattern) => enumerator
+ *     enum.slice_before(pattern) => an_enumerator
- *     enum.slice_before {|elt| bool } => enumerator
+ *     enum.slice_before {|elt| bool } => an_enumerator
- *     enum.slice_before(initial_state) {|elt, state| bool } => enumerator
+ *     enum.slice_before(initial_state) {|elt, state| bool } => an_enumerator
  *
  *  Creates an enumerator for each chunked elements.
  *  The beginnings of chunks are defined by _pattern_ and the block.

error.c

@@ -1058,7 +1058,7 @@ syserr_errno(VALUE self)
  *   system_call_error === other  => true or false
  *
  * Return +true+ if the receiver is a generic +SystemCallError+, or
- * if the error numbers _self_ and _other_ are the same.
+ * if the error numbers +self+ and _other_ are the same.
  */
 
 static VALUE

gc.c

@@ -2424,6 +2424,7 @@ os_obj_of(VALUE of)
 /*
  *  call-seq:
  *     ObjectSpace.each_object([module]) {|obj| ... } => fixnum
+ *     ObjectSpace.each_object([module])              => an_enumerator
  *
  *  Calls the block once for each living, nonimmediate object in this
  *  Ruby process. If <i>module</i> is specified, calls the block
@@ -2435,6 +2436,8 @@ os_obj_of(VALUE of)
  *  returns both the numbers we defined and several constants defined in
  *  the <code>Math</code> module.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     a = 102.7
  *     b = 95       # Won't be returned
  *     c = 12345678987654321

hash.c

@@ -882,10 +882,13 @@ delete_if_i(VALUE key, VALUE value, VALUE hash)
 /*
  *  call-seq:
  *     hsh.delete_if {| key, value | block }  -> hsh
+ *     hsh.delete_if                          -> an_enumerator
  *
  *  Deletes every key-value pair from <i>hsh</i> for which <i>block</i>
  *  evaluates to <code>true</code>.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     h = { "a" => 100, "b" => 200, "c" => 300 }
  *     h.delete_if {|key, value| key >= "b" }   #=> {"a"=>100}
  *
@@ -903,6 +906,7 @@ rb_hash_delete_if(VALUE hash)
 /*
  *  call-seq:
  *     hsh.reject! {| key, value | block }  -> hsh or nil
+ *     hsh.reject!                          -> an_enumerator
  *
  *  Equivalent to <code>Hash#delete_if</code>, but returns
  *  <code>nil</code> if no changes were made.
@@ -974,9 +978,12 @@ select_i(VALUE key, VALUE value, VALUE result)
 /*
  *  call-seq:
  *     hsh.select {|key, value| block}   => a_hash
+ *     hsh.select                        => an_enumerator
  *
  *  Returns a new hash consisting of entries for which the block returns true.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     h = { "a" => 100, "b" => 200, "c" => 300 }
  *     h.select {|k,v| k > "a"}  #=> {"b" => 200, "c" => 300}
  *     h.select {|k,v| v < 200}  #=> {"a" => 100}
@@ -1006,6 +1013,7 @@ keep_if_i(VALUE key, VALUE value, VALUE hash)
 /*
  *  call-seq:
  *     hsh.select! {| key, value | block }  -> hsh or nil
+ *     hsh.select!                          -> an_enumerator
  *
  *  Equivalent to <code>Hash#keep_if</code>, but returns
  *  <code>nil</code> if no changes were made.
@@ -1029,9 +1037,12 @@ rb_hash_select_bang(VALUE hash)
 /*
  *  call-seq:
  *     hsh.keep_if {| key, value | block }  -> hsh
+ *     hsh.keep_if                          -> an_enumerator
  *
  *  Deletes every key-value pair from <i>hsh</i> for which <i>block</i>
- *  evaluates to <code>false</code>.
+ *  evaluates to false.
+ *
+ *  If no block is given, an enumerator is returned instead.
  *
  */
 
@@ -1203,10 +1214,13 @@ each_value_i(VALUE key, VALUE value)
 /*
  *  call-seq:
  *     hsh.each_value {| value | block } -> hsh
+ *     hsh.each_value                    -> an_enumerator
  *
  *  Calls <i>block</i> once for each key in <i>hsh</i>, passing the
  *  value as a parameter.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     h = { "a" => 100, "b" => 200 }
  *     h.each_value {|value| puts value }
  *
@@ -1235,10 +1249,13 @@ each_key_i(VALUE key, VALUE value)
 /*
  *  call-seq:
  *     hsh.each_key {| key | block } -> hsh
+ *     hsh.each_key                  -> an_enumerator
  *
  *  Calls <i>block</i> once for each key in <i>hsh</i>, passing the key
  *  as a parameter.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     h = { "a" => 100, "b" => 200 }
  *     h.each_key {|key| puts key }
  *
@@ -1267,10 +1284,14 @@ each_pair_i(VALUE key, VALUE value)
  *  call-seq:
  *     hsh.each      {| key, value | block } -> hsh
  *     hsh.each_pair {| key, value | block } -> hsh
+ *     hsh.each                              -> an_enumerator
+ *     hsh.each_pair                         -> an_enumerator
  *
  *  Calls <i>block</i> once for each key in <i>hsh</i>, passing the key-value
  *  pair as parameters.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     h = { "a" => 100, "b" => 200 }
  *     h.each {|key, value| puts "#{key} is #{value}" }
  *
@@ -1377,7 +1398,7 @@ rb_hash_inspect(VALUE hash)
  * call-seq:
  *    hsh.to_hash   => hsh
  *
- * Returns <i>self</i>.
+ * Returns +self+.
  */
 
 static VALUE

io.c

@@ -2703,17 +2703,17 @@ rb_io_readlines(int argc, VALUE *argv, VALUE io)
  *     ios.each(sep=$/) {|line| block }         => ios
  *     ios.each(limit) {|line| block }          => ios
  *     ios.each(sep,limit) {|line| block }      => ios
- *     ios.each(...)                            => anEnumerator
+ *     ios.each(...)                            => an_enumerator
  *
  *     ios.each_line(sep=$/) {|line| block }    => ios
  *     ios.each_line(limit) {|line| block }     => ios
  *     ios.each_line(sep,limit) {|line| block } => ios
- *     ios.each_line(...)                       => anEnumerator
+ *     ios.each_line(...)                       => an_enumerator
  *
  *     ios.lines(sep=$/) {|line| block }        => ios
  *     ios.lines(limit) {|line| block }         => ios
  *     ios.lines(sep,limit) {|line| block }     => ios
- *     ios.lines(...)                           => anEnumerator
+ *     ios.lines(...)                           => an_enumerator
  *
  *  Executes the block for every line in <em>ios</em>, where lines are
  *  separated by <i>sep</i>. <em>ios</em> must be opened for
@@ -2749,10 +2749,10 @@ rb_io_each_line(int argc, VALUE *argv, VALUE io)
 /*
  *  call-seq:
  *     ios.bytes {|byte| block }      => ios
- *     ios.bytes                      => anEnumerator
+ *     ios.bytes                      => an_enumerator
  *
  *     ios.each_byte {|byte| block }  => ios
- *     ios.each_byte                  => anEnumerator
+ *     ios.each_byte                  => an_enumerator
  *
  *  Calls the given block once for each byte (0..255) in <em>ios</em>,
  *  passing the byte as an argument. The stream must be opened for
@@ -2898,10 +2898,10 @@ io_getc(rb_io_t *fptr, rb_encoding *enc)
 /*
  *  call-seq:
  *     ios.chars {|c| block }      => ios
- *     ios.chars                   => anEnumerator
+ *     ios.chars                   => an_enumerator
  *
  *     ios.each_char {|c| block }  => ios
- *     ios.each_char               => anEnumerator
+ *     ios.each_char               => an_enumerator
  *
  *  Calls the given block once for each character in <em>ios</em>,
  *  passing the character as an argument. The stream must be opened for
@@ -2933,23 +2933,19 @@ rb_io_each_char(VALUE io)
 }
 
 
-
-/*
- *  call-seq:
- *     ios.codepoints   => anEnumerator
- *
- *  Returns an enumerator that gives each codepoint in <em>ios</em>.
- *  The stream must be opened for reading or an <code>IOError</code>
- *  will be raised.
- */
-
 /*
  *  call-seq:
  *     ios.each_codepoint {|c| block }  => ios
+ *     ios.codepoints     {|c| block }  => ios
+ *     ios.each_codepoint               => an_enumerator
+ *     ios.codepoints                   => an_enumerator
  *
  *  Passes the <code>Integer</code> ordinal of each character in <i>ios</i>,
  *  passing the codepoint as an argument. The stream must be opened for
  *  reading or an <code>IOError</code> will be raised.
+ *
+ *  If no block is given, an enumerator is returned instead.
+ *
  */
 
 static VALUE
@@ -7833,10 +7829,13 @@ io_s_foreach(struct foreach_arg *arg)
  *     IO.foreach(name, sep=$/ [, open_args]) {|line| block }     => nil
  *     IO.foreach(name, limit [, open_args]) {|line| block }      => nil
  *     IO.foreach(name, sep, limit [, open_args]) {|line| block } => nil
+ *     IO.foreach(...)                                            => an_enumerator
  *
  *  Executes the block for every line in the named I/O port, where lines
  *  are separated by <em>sep</em>.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     IO.foreach("testfile") {|x| print "GOT ", x }
  *
  *  <em>produces:</em>
@@ -9222,15 +9221,15 @@ argf_readbyte(VALUE argf)
  *  call-seq:
  *     ARGF.each(sep=$/)            {|line| block }  => ARGF
  *     ARGF.each(sep=$/,limit)      {|line| block }  => ARGF
- *     ARGF.each(...)                                => anEnumerator
+ *     ARGF.each(...)                                => an_enumerator
  *
  *     ARGF.each_line(sep=$/)       {|line| block }  => ARGF
  *     ARGF.each_line(sep=$/,limit) {|line| block }  => ARGF
- *     ARGF.each_line(...)                           => anEnumerator
+ *     ARGF.each_line(...)                           => an_enumerator
  *
  *     ARGF.lines(sep=$/)           {|line| block }   => ARGF
  *     ARGF.lines(sep=$/,limit)     {|line| block }   => ARGF
- *     ARGF.lines(...)                                => anEnumerator
+ *     ARGF.lines(...)                                => an_enumerator
  *
  *  Returns an enumerator which iterates over each line (separated by _sep_,
  *  which defaults to your platform's newline character) of each file in
@@ -9268,10 +9267,10 @@ argf_each_line(int argc, VALUE *argv, VALUE argf)
 /*
  *  call-seq:
  *     ARGF.bytes     {|byte| block }  => ARGF
- *     ARGF.bytes                      => anEnumerator
+ *     ARGF.bytes                      => an_enumerator
  *
  *     ARGF.each_byte {|byte| block }  => ARGF
- *     ARGF.each_byte                  => anEnumerator
+ *     ARGF.each_byte                  => an_enumerator
  *
  *  Iterates over each byte of each file in +ARGV+.
  *  A byte is returned as a +Fixnum+ in the range 0..255.
@@ -9303,10 +9302,10 @@ argf_each_byte(VALUE argf)
 /*
  *  call-seq:
  *     ARGF.chars      {|char| block }  => ARGF
- *     ARGF.chars                       => anEnumerator
+ *     ARGF.chars                       => an_enumerator
  *
  *     ARGF.each_char  {|char| block }  => ARGF
- *     ARGF.each_char                   => anEnumerator
+ *     ARGF.each_char                   => an_enumerator
  *
  *  Iterates over each character of each file in +ARGF+.
  *
@@ -9590,9 +9589,9 @@ ruby_set_inplace_mode(const char *suffix)
 
 /*
  *  call-seq:
- *     ARGF.argv  => Array
+ *     ARGF.argv  => ARGV
  *
- *  Returns the +ARGV+ Array, which contains the arguments passed to your
+ *  Returns the +ARGV+ array, which contains the arguments passed to your
  *  script, one per element.
  *
  *  For example:

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

range.c

@@ -319,6 +319,7 @@ discrete_object_p(VALUE obj)
 /*
  *  call-seq:
  *     rng.step(n=1) {| obj | block }    => rng
+ *     rng.step(n=1)                     => an_enumerator
  *
  *  Iterates over <i>rng</i>, passing each <i>n</i>th element to the block. If
  *  the range contains numbers, <i>n</i> is added for each iteration.  Otherwise
@@ -326,6 +327,8 @@ discrete_object_p(VALUE obj)
  *  elements. The following code uses class <code>Xs</code>, which is defined
  *  in the class-level documentation.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     range = Xs.new(1)..Xs.new(10)
  *     range.step(2) {|x| puts x}
  *     range.step(3) {|x| puts x}
@@ -453,12 +456,15 @@ sym_each_i(VALUE v, void *arg)
 /*
  *  call-seq:
  *     rng.each {| i | block } => rng
+ *     rng.each                => an_enumerator
  *
  *  Iterates over the elements <i>rng</i>, passing each in turn to the
  *  block. You can only iterate if the start object of the range
  *  supports the +succ+ method (which means that you can't iterate over
  *  ranges of +Float+ objects).
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     (10..15).each do |n|
  *        print n, ' '
  *     end

string.c

@@ -2859,13 +2859,16 @@ rb_str_succ_bang(VALUE str)
 /*
  *  call-seq:
  *     str.upto(other_str, exclusive=false) {|s| block }   => str
+ *     str.upto(other_str, exclusive=false)                => an_enumerator
  *
  *  Iterates through successive values, starting at <i>str</i> and
  *  ending at <i>other_str</i> inclusive, passing each value in turn to
  *  the block. The <code>String#succ</code> method is used to generate
- *  each value.  If optional second argument exclusive is omitted or is <code>false</code>,
+ *  each value.  If optional second argument exclusive is omitted or is false,
  *  the last value will be included; otherwise it will be excluded.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     "a8".upto("b6") {|s| print s, ' ' }
  *     for s in "a8".."b6"
  *       print s, ' '
@@ -3548,6 +3551,7 @@ rb_str_sub_bang(int argc, VALUE *argv, VALUE str)
  *  call-seq:
  *     str.sub(pattern, replacement)         => new_str
  *     str.sub(pattern) {|match| block }     => new_str
+ *     str.sub(pattern)                      => an_enumerator
  *
  *  Returns a copy of <i>str</i> with the <em>first</em> occurrence of
  *  <i>pattern</i> replaced with either <i>replacement</i> or the value of the
@@ -3566,6 +3570,8 @@ rb_str_sub_bang(int argc, VALUE *argv, VALUE str)
  *  <code>$&</code>, and <code>$'</code> will be set appropriately. The value
  *  returned by the block will be substituted for the match on each call.
  *
+ *  If no block and no <i>replacement</i> is given, an enumerator is returned instead.
+ *
  *  The result inherits any tainting in the original string or any supplied
  *  replacement string.
  *
@@ -5659,10 +5665,10 @@ rb_str_split(VALUE str, const char *sep0)
 /*
  *  call-seq:
  *     str.each_line(separator=$/) {|substr| block }   => str
- *     str.each_line(separator=$/)                     => anEnumerator
+ *     str.each_line(separator=$/)                     => an_enumerator
  *
  *     str.lines(separator=$/) {|substr| block }       => str
- *     str.lines(separator=$/)                         => anEnumerator
+ *     str.lines(separator=$/)                         => an_enumerator
  *
  *  Splits <i>str</i> using the supplied parameter as the record separator
  *  (<code>$/</code> by default), passing each substring in turn to the supplied
@@ -5794,10 +5800,10 @@ rb_str_each_line(int argc, VALUE *argv, VALUE str)
 /*
  *  call-seq:
  *     str.bytes {|fixnum| block }        => str
- *     str.bytes                          => anEnumerator
+ *     str.bytes                          => an_enumerator
  *
  *     str.each_byte {|fixnum| block }    => str
- *     str.each_byte                      => anEnumerator
+ *     str.each_byte                      => an_enumerator
  *
  *  Passes each byte in <i>str</i> to the given block, or returns
  *  an enumerator if no block is given.
@@ -5825,10 +5831,10 @@ rb_str_each_byte(VALUE str)
 /*
  *  call-seq:
  *     str.chars {|cstr| block }        => str
- *     str.chars                        => anEnumerator
+ *     str.chars                        => an_enumerator
  *
  *     str.each_char {|cstr| block }    => str
- *     str.each_char                    => anEnumerator
+ *     str.each_char                    => an_enumerator
  *
  *  Passes each character in <i>str</i> to the given block, or returns
  *  an enumerator if no block is given.
@@ -5873,10 +5879,10 @@ rb_str_each_char(VALUE str)
 /*
  *  call-seq:
  *     str.codepoints {|integer| block }        => str
- *     str.codepoints                           => anEnumerator
+ *     str.codepoints                           => an_enumerator
  *
  *     str.each_codepoint {|integer| block }    => str
- *     str.each_codepoint                       => anEnumerator
+ *     str.each_codepoint                       => an_enumerator
  *
  *  Passes the <code>Integer</code> ordinal of each character in <i>str</i>,
  *  also known as a <i>codepoint</i> when applied to Unicode strings to the

struct.c

@@ -442,10 +442,13 @@ rb_struct_new(VALUE klass, ...)
 /*
  *  call-seq:
  *     struct.each {|obj| block }  => struct
+ *     struct.each                 => an_enumerator
  *
  *  Calls <i>block</i> once for each instance variable, passing the
  *  value as a parameter.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     Customer = Struct.new(:name, :address, :zip)
  *     joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
  *     joe.each {|x| puts(x) }
@@ -472,10 +475,13 @@ rb_struct_each(VALUE s)
 /*
  *  call-seq:
  *     struct.each_pair {|sym, obj| block }     => struct
+ *     struct.each_pair                         => an_enumerator
  *
  *  Calls <i>block</i> once for each instance variable, passing the name
  *  (as a symbol) and the value as parameters.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     Customer = Struct.new(:name, :address, :zip)
  *     joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
  *     joe.each_pair {|name, value| puts("#{name} => #{value}") }
@@ -734,7 +740,7 @@ struct_entry(VALUE s, long n)
  *   struct.values_at(selector,... )  => an_array
  *
  *   Returns an array containing the elements in
- *   _self_ corresponding to the given selector(s). The selectors
+ *   +self+ corresponding to the given selector(s). The selectors
  *   may be either integer indices or ranges.
  *   See also </code>.select<code>.
  *
@@ -754,6 +760,7 @@ rb_struct_values_at(int argc, VALUE *argv, VALUE s)
 /*
  *  call-seq:
  *     struct.select {|i| block }    => array
+ *     struct.select                 => an_enumerator
  *
  *  Invokes the block passing in successive elements from
  *  <i>struct</i>, returning an array containing those elements

vm_eval.c

@@ -792,10 +792,13 @@ loop_i(void)
 
 /*
  *  call-seq:
- *     loop {|| block }
+ *     loop { block }
+ *     loop            -> an_enumerator
  *
  *  Repeatedly executes the block.
  *
+ *  If no block is given, an enumerator is returned instead.
+ *
  *     loop do
  *       print "Input: "
  *       line = gets