* 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, 24 insertions, 3 deletions

diff --git a/hash.c b/hash.c
index 354593457d..55809e3375 100644
--- a/hash.c
+++ b/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 }
  *
@@ -1265,12 +1282,16 @@ each_pair_i(VALUE key, VALUE value)
 
 /*
  *  call-seq:
- *     hsh.each {| key, value | block } -> hsh
+ *     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