From: Yusuke Endoh <mame@...>
Date: 2011-05-25T01:42:27+09:00
Subject: [ruby-core:36433] [Ruby 1.9 - Bug #4757][Open] Attempt to make Enumerator docs more clear (patch included)


Issue #4757 has been updated by Yusuke Endoh.

Status changed from Closed to Open

Hello,

- *   p e.next   #=> 1
- *   p e.next   #=> 2
- *   p e.next   #=> 3
- *   p e.next   #raises StopIteration
+ *   puts e.next   # => 1
+ *   puts e.next   # => 2
+ *   puts e.next   # => 3
+ *   puts e.next   # raises StopIteration

Why did you use puts than p?


- * Note that enumeration sequence by next_values method does not affect other
- * non-external enumeration methods, unless underlying iteration
- * methods itself has side-effect, e.g. IO#each_line.
+ * Note that enumeration sequenced by +next_values+ does not affect other
+ * non-external enumeration methods, unless underlying iteration methods
+ * itself has side-effect, e.g. IO#each_line.

I cannot undestand what "enumeration sequence by next_values" is.
This is a problem of the original rdoc, not yours, though.
It might be good to remove "enumeration sequence by".

The old rdoc was written by akr.  Akr, what did you mean?


- *   o = Object.new
- *   def o.each
- *     # (2)
- *     x = yield
- *     p x          #=> "foo"
- *     # (5)
- *     x = yield
- *     p x          #=> nil
- *     # (7)
- *     x = yield
- *     # not reached
- *     p x
- *   end
- *   e = o.to_enum
- *   # (1)
- *   e.next
- *   # (3)
- *   e.feed "foo"
- *   # (4)
- *   e.next
- *   # (6)
- *   e.next
- *   # (8)
+ *   three_times = Enumerator.new do |yielder|
+ *     3.times do |x|
+ *       result = yielder.yield(x)
+ *       puts result
+ *     end
+ *   end
+ *   three_times.next # => 0
+ *   three_times.feed("foo")
+ *   three_times.next # => 1, prints "foo"
+ *   three_times.next # => 2, prints nothing

It became worse (to me).
(1) (2) (3)... meant the evaluation order.  I believe that
this is helpful for newbie to understand it.

-- 
Yusuke Endoh <mame@tsg.ne.jp>
----------------------------------------
Bug #4757: Attempt to make Enumerator docs more clear (patch included)
http://redmine.ruby-lang.org/issues/4757

Author: David Copeland
Status: Open
Priority: Normal
Assignee: Eric Hodel
Category: DOC
Target version: 
ruby -v: ruby 1.9.3dev (2011-05-16 trunk 31583) [x86_64-darwin10.7.0]


The Enumerator docs aren't super clear; these make it more clear, at least to me, and also more consistent.


-- 
http://redmine.ruby-lang.org