From df3e4b830677e41530402e3e5727b71551fbe666 Mon Sep 17 00:00:00 2001
From: zzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
Date: Fri, 20 Sep 2013 15:51:17 +0000
Subject: * enumerator.c: [DOC] Enumerator#each arguments documentation
 [GH-388]   Patch by @kachick  https://github.com/ruby/ruby/pull/388

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@43000 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
---
 ChangeLog    |  5 +++++
 enumerator.c | 34 +++++++++++++++++++++++++++++++---
 2 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index fa21604a69..c8b9c601ef 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+Sat Sep 21 00:50:02 2013  Zachary Scott  <e@zzak.io>
+
+	* enumerator.c: [DOC] Enumerator#each arguments documentation [GH-388]
+	  Patch by @kachick  https://github.com/ruby/ruby/pull/388
+
 Sat Sep 21 00:49:16 2013  Zachary Scott  <e@zzak.io>
 
 	* enum.c: [DOC] Enumerable#to_a accepts arguments [GH-388]
diff --git a/enumerator.c b/enumerator.c
index 6f3de864a0..5794454f16 100644
--- a/enumerator.c
+++ b/enumerator.c
@@ -434,10 +434,38 @@ enumerator_block_call(VALUE obj, rb_block_call_func *func, VALUE arg)
 
 /*
  * call-seq:
- *   enum.each {...}
+ *   enum.each { |elm| block }                    -> obj
+ *   enum.each                                    -> enum
+ *   enum.each(*appending_args) { |elm| block }   -> obj
+ *   enum.each(*appending_args)                   -> an_enumerator
  *
- * Iterates over the block according to how this Enumerable was constructed.
- * If no block is given, returns self.
+ * Iterates over the block according to how this Enumerator was constructed.
+ * If no block and no arguments are given, returns self.
+ *
+ * === Examples
+ *
+ *   "Hello, world!".scan(/\w+/)                     #=> ["Hello", "world"]
+ *   "Hello, world!".to_enum(:scan, /\w+/).to_a      #=> ["Hello", "world"]
+ *   "Hello, world!".to_enum(:scan).each(/\w+/).to_a #=> ["Hello", "world"]
+ *
+ *   obj = Object.new
+ *
+ *   def obj.each_arg(a, b=:b, *rest)
+ *     yield a
+ *     yield b
+ *     yield rest
+ *     :method_returned
+ *   end
+ *
+ *   enum = obj.to_enum :each_arg, :a, :x
+ *
+ *   enum.each.to_a                  #=> [:a, :x, []]
+ *   enum.each.equal?(enum)          #=> true
+ *   enum.each { |elm| elm }         #=> :method_returned
+ *
+ *   enum.each(:y, :z).to_a          #=> [:a, :x, [:y, :z]]
+ *   enum.each(:y, :z).equal?(enum)  #=> false
+ *   enum.each(:y, :z) { |elm| elm } #=> :method_returned
  *
  */
 static VALUE
-- 
cgit v1.2.3