Extra formatting and clarification of enumerator_feed [#4757]

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

enumerator.c

@@ -714,26 +714,30 @@ enumerator_peek(VALUE obj)
  * call-seq:
  *   e.feed obj   -> nil
  *
- * Set the value to be returned by the next call to +yield+ by the enumerator.
- * If the value is not set, the +yield+ returns +nil+ and the value is cleared
- * after it is used the first time.
+ * Set the value for the next yield in the enumerator returns.
  *
- * +obj+:: the object to return from the next call to the Enumerator's +yield+
+ * If the value is not set, the yield returns nil.
  *
- * === Example
+ * This value is cleared after being used.
  *
- *   three_times = Enumerator.new do |yielder|
- *     3.times do |x|
- *       result = yielder.yield(x)
- *       puts result
- *     end
+ *   o = Object.new
+ *   def o.each
+ *     x = yield         # (2) blocks
+ *     p x               # (5) => "foo"
+ *     x = yield         # (6) blocks
+ *     p x               # (8) => nil
+ *     x = yield         # (9) blocks
+ *     p x               # not reached w/o another e.next
  *   end
  *
- *   three_times.next # => 0
- *   three_times.feed("foo")
- *   three_times.next # => 1, prints "foo"
- *   three_times.next # => 2, prints nothing
+ *   e = o.to_enum
+ *   e.next              # (1)
+ *   e.feed "foo"        # (3)
+ *   e.next              # (4)
+ *   e.next              # (7)
+ *                       # (10)
  */
+
 static VALUE
 enumerator_feed(VALUE obj, VALUE v)
 {