* 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>