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

Issue #1666 has been updated by Yusuke Endoh.


Hi,

> 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.

I think the inconsistency is caused by accident.  Traditionally,
String#lines had returned an Enumerator ignoring a given block.
And it was changed at r11186 because of [ruby-core:09218].
I can find no reason why IO#lines are not changed similarly.
I guess it is just forgotten.


In addition, ARGF works similarly to String:

  $ echo -e "foo\nbar\nbaz" | ./ruby -e '$<.lines {|x| p x }'
  "foo\n"
  "bar\n"
  "baz\n"

  $ echo -e "foo\nbar\nbaz" | ./ruby -e 'p $<.to_io.lines {|x| p x }'

This is apparently strange.  So, I'll fix it soon by changing IO#
lines, etc.  I'll also fix RubySpec.
(Of course, I'll revert this if matz says this is intended)


> the documentation is different for String#lines vs String#each_line, #bytes vs #each_byte, #chars vs #each_char  (although they are aliases).

Seems the same historical reason.

However, I wonder matz may still want people to use #each_line to
iterate and #lines to make an Enumerator, respectively.


> StringIO#bytes, #lines & #chars are not documented at all.
> In all cases, the documentation for String should be cleaned up

As you can see, my English is very poor.  So I'll leave it to you.
Before you commit, please let us review a patch.

-- 
Yusuke Endoh <[e-mail]>
----------------------------------------
http://redmine.ruby-lang.org/issues/show/1666

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