[ruby-core:23948] [Bug #1666] Confusion in documentation for lines vs each_line, etc...

Bug #1666: Confusion in documentation for lines vs each_line, etc...
http://redmine.ruby-lang.org/issues/show/1666

Author: Marc-Andre Lafortune
Status: Open, Priority: Normal
Category: core, Target version: 1.9.2
ruby -v: ruby 1.9.2dev (2009-06-20 trunk 23755) [i386-darwin9.7.0]

Currently, IO#lines is defined as "to_enum(:each_line, *args)" and thus will ignore a block if one is given.
On the other hand, String#lines and String#each_line are aliases, and thus will both execute the block, if one given. The same is true for StringIO#lines and StringIO#each_line.

The same distinction exist in IO for #bytes vs #each_byte, #chars vs #each_char, while these pairs are aliases in String and StringIO.

To add to the confusion, the documentation is different for String#lines vs String#each_line, #bytes vs #each_byte, #chars vs #each_char  (although they are aliases). StringIO#bytes, #lines & #chars are not documented at all.

So either:
1) there should not be a distinction (and IO's implementation and doc should be changed to reflect that)
or 2) the distinction is intentional (and String + StringIO's implementation should be changed to relect that)
or 3) there is a compelling reason why the behavior in IO should be different than in String and StringIO and that should be spelled out in the doc.

In all cases, the documentation for String should be cleaned up; for example String#each_char doesn't state that an enumerator is returned if no block is given (contrary to the doc for String#chars) and the examples are wrong since they use #each (which no longer exists) instead of #each_char.

Finally, the pair #codepoints and #each_codepoint is in a similar mismatch of documentation in String. I'll post a separate feature request to add IO#codepoints, etc...


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