Add documentation for `chomp` option.

  https://github.com/ruby/ruby/pull/1717

  Patch by @ksss [fix GH-1717]

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

2 files changed, 51 insertions, 32 deletions

diff --git a/io.c b/io.c
index f01dea6873..7392a19013 100644
--- a/io.c
+++ b/io.c
@@ -3293,9 +3293,9 @@ rb_io_gets_internal(VALUE io)
 
 /*
  *  call-seq:
- *     ios.gets(sep=$/)     -> string or nil
- *     ios.gets(limit)      -> string or nil
- *     ios.gets(sep, limit) -> string or nil
+ *     ios.gets(sep=$/ [, getline_args])     -> string or nil
+ *     ios.gets(limit [, getline_args])      -> string or nil
+ *     ios.gets(sep, limit [, getline_args]) -> string or nil
  *
  *  Reads the next ``line'' from the I/O stream; lines are separated by
  *  <i>sep</i>. A separator of +nil+ reads the entire
@@ -3397,9 +3397,9 @@ rb_io_set_lineno(VALUE io, VALUE lineno)
 
 /*
  *  call-seq:
- *     ios.readline(sep=$/)     -> string
- *     ios.readline(limit)      -> string
- *     ios.readline(sep, limit) -> string
+ *     ios.readline(sep=$/ [, getline_args])     -> string
+ *     ios.readline(limit [, getline_args])      -> string
+ *     ios.readline(sep, limit [, getline_args]) -> string
  *
  *  Reads a line as with <code>IO#gets</code>, but raises an
  *  <code>EOFError</code> on end of file.
@@ -3420,20 +3420,23 @@ static VALUE io_readlines(const struct getline_arg *arg, VALUE io);
 
 /*
  *  call-seq:
- *     ios.readlines(sep=$/)     -> array
- *     ios.readlines(limit)      -> array
- *     ios.readlines(sep, limit) -> array
+ *     ios.readlines(sep=$/ [, getline_args])     -> array
+ *     ios.readlines(limit [, getline_args])      -> array
+ *     ios.readlines(sep, limit [, getline_args]) -> array
  *
  *  Reads all of the lines in <em>ios</em>, and returns them in
  *  <i>anArray</i>. Lines are separated by the optional <i>sep</i>. If
  *  <i>sep</i> is +nil+, the rest of the stream is returned
- *  as a single record.  If the first argument is an integer, or
+ *  as a single record.
+ *  If the first argument is an integer, or
  *  optional second argument is given, the returning string would not be
  *  longer than the given value in bytes. The stream must be opened for
  *  reading or an <code>IOError</code> will be raised.
  *
  *     f = File.new("testfile")
  *     f.readlines[0]   #=> "This is line one\n"
+ *
+ *  See <code>IO.readlines</code> for detail about getline_args.
  */
 
 static VALUE
@@ -3461,14 +3464,14 @@ io_readlines(const struct getline_arg *arg, VALUE io)
 
 /*
  *  call-seq:
- *     ios.each(sep=$/)          {|line| block } -> ios
- *     ios.each(limit)           {|line| block } -> ios
- *     ios.each(sep, limit)      {|line| block } -> ios
+ *     ios.each(sep=$/ [, getline_args])          {|line| block } -> ios
+ *     ios.each(limit [, getline_args])           {|line| block } -> ios
+ *     ios.each(sep, limit [, getline_args])      {|line| block } -> ios
  *     ios.each(...)                             -> an_enumerator
  *
- *     ios.each_line(sep=$/)     {|line| block } -> ios
- *     ios.each_line(limit)      {|line| block } -> ios
- *     ios.each_line(sep, limit) {|line| block } -> ios
+ *     ios.each_line(sep=$/ [, getline_args])     {|line| block } -> ios
+ *     ios.each_line(limit [, getline_args])      {|line| block } -> ios
+ *     ios.each_line(sep, limit [, getline_args]) {|line| block } -> ios
  *     ios.each_line(...)                        -> an_enumerator
  *
  *  Executes the block for every line in <em>ios</em>, where lines are
@@ -3486,6 +3489,8 @@ io_readlines(const struct getline_arg *arg, VALUE io)
  *     2: This is line two
  *     3: This is line three
  *     4: And so on...
+ *
+ *  See <code>IO.readlines</code> for detail about getline_args.
  */
 
 static VALUE
@@ -8426,9 +8431,9 @@ static VALUE argf_gets(int, VALUE *, VALUE);
 
 /*
  *  call-seq:
- *     gets(sep=$/)     -> string or nil
- *     gets(limit)      -> string or nil
- *     gets(sep, limit) -> string or nil
+ *     gets(sep=$/ [, getline_args])     -> string or nil
+ *     gets(limit [, getline_args])      -> string or nil
+ *     gets(sep, limit [, getline_args]) -> string or nil
  *
  *  Returns (and assigns to <code>$_</code>) the next line from the list
  *  of files in +ARGV+ (or <code>$*</code>), or from standard input if
@@ -8468,9 +8473,9 @@ rb_f_gets(int argc, VALUE *argv, VALUE recv)
 
 /*
  *  call-seq:
- *     ARGF.gets(sep=$/)     -> string or nil
- *     ARGF.gets(limit)      -> string or nil
- *     ARGF.gets(sep, limit) -> string or nil
+ *     ARGF.gets(sep=$/ [, getline_args])     -> string or nil
+ *     ARGF.gets(limit [, getline_args])      -> string or nil
+ *     ARGF.gets(sep, limit [, getline_args]) -> string or nil
  *
  *  Returns the next line from the current file in +ARGF+.
  *
@@ -8481,6 +8486,8 @@ rb_f_gets(int argc, VALUE *argv, VALUE recv)
  *  The optional _limit_ argument specifies how many characters of each line
  *  to return. By default all characters are returned.
  *
+ *  See <code>IO.readlines</code> for detail about getline_args.
+ *
  */
 static VALUE
 argf_gets(int argc, VALUE *argv, VALUE argf)
@@ -10006,9 +10013,9 @@ io_s_foreach(struct getline_arg *arg)
 
 /*
  *  call-seq:
- *     IO.foreach(name, sep=$/ [, open_args]) {|line| block }     -> nil
- *     IO.foreach(name, limit [, open_args]) {|line| block }      -> nil
- *     IO.foreach(name, sep, limit [, open_args]) {|line| block } -> nil
+ *     IO.foreach(name, sep=$/ [, getline_args, open_args]) {|line| block }     -> nil
+ *     IO.foreach(name, limit [, getline_args, open_args]) {|line| block }      -> nil
+ *     IO.foreach(name, sep, limit [, getline_args, open_args]) {|line| block } -> nil
  *     IO.foreach(...)                                            -> an_enumerator
  *
  *  Executes the block for every line in the named I/O port, where lines
@@ -10026,7 +10033,8 @@ io_s_foreach(struct getline_arg *arg)
  *     GOT And so on...
  *
  *  If the last argument is a hash, it's the keyword argument to open.
- *  See <code>IO.read</code> for detail.
+ *  See <code>IO.readlines</code> for detail about getline_args.
+ *  And see also <code>IO.read</code> for detail about open_args.
  *
  */
 
@@ -10056,9 +10064,9 @@ io_s_readlines(struct getline_arg *arg)
 
 /*
  *  call-seq:
- *     IO.readlines(name, sep=$/ [, open_args])     -> array
- *     IO.readlines(name, limit [, open_args])      -> array
- *     IO.readlines(name, sep, limit [, open_args]) -> array
+ *     IO.readlines(name, sep=$/ [, getline_args, open_args])     -> array
+ *     IO.readlines(name, limit [, getline_args, open_args])      -> array
+ *     IO.readlines(name, sep, limit [, getline_args, open_args]) -> array
  *
  *  Reads the entire file specified by <i>name</i> as individual
  *  lines, and returns those lines in an array. Lines are separated by
@@ -10068,7 +10076,16 @@ io_s_readlines(struct getline_arg *arg)
  *     a[0]   #=> "This is line one\n"
  *
  *  If the last argument is a hash, it's the keyword argument to open.
- *  See <code>IO.read</code> for detail.
+ *
+ *  === Option for getline
+ *
+ *  The options hash accepts the following keys:
+ *
+ *  :chomp::
+ *    Specifies the boolean. It will remove \n, \r, and \r\n
+ *    from the end of each lines if it's true
+ *
+ *  And see also <code>IO.read</code> for detail about open_args.
  *
  */
 
diff --git a/string.c b/string.c
index 604304fda2..c1e986fb9a 100644
--- a/string.c
+++ b/string.c
@@ -7760,8 +7760,8 @@ rb_str_enumerate_lines(int argc, VALUE *argv, VALUE str, VALUE ary)
 
 /*
  *  call-seq:
- *     str.each_line(separator=$/) {|substr| block }   -> str
- *     str.each_line(separator=$/)                     -> an_enumerator
+ *     str.each_line(separator=$/ [, getline_args]) {|substr| block } -> str
+ *     str.each_line(separator=$/ [, getline_args])                   -> an_enumerator
  *
  *  Splits <i>str</i> using the supplied parameter as the record
  *  separator (<code>$/</code> by default), passing each substring in
@@ -7769,6 +7769,8 @@ rb_str_enumerate_lines(int argc, VALUE *argv, VALUE str, VALUE ary)
  *  supplied, the string is split into paragraphs delimited by
  *  multiple successive newlines.
  *
+ *  See <code>IO.readlines</code> for detail about getline_args.
+ *
  *  If no block is given, an enumerator is returned instead.
  *
  *     print "Example one\n"