Enhanced RDoc for io.c (#5573)

Links to options doc added/improved; in particular, new links to new section "Encoding Options" in encoding.rdoc.  Minor inconsistencies ironed out.

1 files changed, 81 insertions, 61 deletions

diff --git a/io.c b/io.c
index 24488d2db7..efe37ca835 100644
--- a/io.c
+++ b/io.c
@@ -4042,8 +4042,8 @@ rb_io_gets_internal(VALUE io)
  *    or +nil+ if none.
  *  - But returns no more bytes than are allowed by the limit.
  *
- *  For all forms above, trailing optional keyword arguments may be given;
- *  see {Line Options}[rdoc-ref:IO@Line+Options]:
+ *  For all forms above, optional keyword arguments +line_opts+ specify
+ *  {Line Options}[rdoc-ref:IO@Line+Options]:
  *
  *    f = File.open('t.txt')
  *    # Chomp the lines.
@@ -4181,8 +4181,8 @@ static VALUE io_readlines(const struct getline_arg *arg, VALUE io);
  *  - Returns lines as determined by line separator +sep+.
  *  - But returns no more bytes in a line than are allowed by the limit.
  *
- *  For all forms above, trailing optional keyword arguments may be given;
- *  see {Line Options}[rdoc-ref:IO@Line+Options]:
+ *  For all forms above, optional keyword arguments +line_opts+ specify
+ *  {Line Options}[rdoc-ref:IO@Line+Options]:
  *
  *    f = File.new('t.txt')
  *    f.readlines(chomp: true)
@@ -4299,8 +4299,8 @@ io_readlines(const struct getline_arg *arg, VALUE io)
  *  - Calls with the next line as determined by line separator +sep+.
  *  - But returns no more bytes than are allowed by the limit.
  *
- *  For all forms above, trailing optional keyword arguments may be given;
- *  see {Line Options}[rdoc-ref:IO@Line+Options]:
+ *  For all forms above, optional keyword arguments +line_opts+ specify
+ *  {Line Options}[rdoc-ref:IO@Line+Options]:
  *
  *    f = File.new('t.txt')
  *    f.each_line(chomp: true) {|line| p line }
@@ -7407,8 +7407,11 @@ static VALUE popen_finish(VALUE port, VALUE klass);
  *      pipe.gets
  *    end => "bar\n"
  *
- *  The optional keyword arguments +opts+ may be {\IO open options}[rdoc-ref:IO@Open+Options]
- *  and options for Kernel#spawn.
+ *  Optional keyword arguments +opts+ specify:
+ *
+ *  - {Open options}[rdoc-ref:IO@Open+Options].
+ *  - {Encoding options}[rdoc-ref:encoding.rdoc@Encoding+Options].
+ *  - Options for Kernel#spawn.
  *
  *  <b>Forked \Process</b>
  *
@@ -7640,8 +7643,8 @@ rb_open_file(int argc, const VALUE *argv, VALUE io)
  *  Document-method: File::open
  *
  *  call-seq:
- *    File.open(path, mode = 'r', perm = 0666, **open_opts) -> file
- *    File.open(path, mode = 'r', perm = 0666, **open_opts) {|f| ... } -> object
+ *    File.open(path, mode = 'r', perm = 0666, **opts) -> file
+ *    File.open(path, mode = 'r', perm = 0666, **opts) {|f| ... } -> object
  *
  *  Creates a new \File object, via File.new with the given arguments.
  *
@@ -7656,8 +7659,8 @@ rb_open_file(int argc, const VALUE *argv, VALUE io)
  *  Document-method: IO::open
  *
  *  call-seq:
- *    IO.open(fd, mode = 'r', **open_opts)             -> io
- *    IO.open(fd, mode = 'r', **open_opts) {|io| ... } -> object
+ *    IO.open(fd, mode = 'r', **opts)             -> io
+ *    IO.open(fd, mode = 'r', **opts) {|io| ... } -> object
  *
  *  Creates a new \IO object, via IO.new with the given arguments.
  *
@@ -7742,8 +7745,8 @@ check_pipe_command(VALUE filename_or_command)
 
 /*
  *  call-seq:
- *    open(path, mode = 'r', perm = 0666, **open_opts)             -> io or nil
- *    open(path, mode = 'r', perm = 0666, **open_opts) {|io| ... } -> obj
+ *    open(path, mode = 'r', perm = 0666, **opts)             -> io or nil
+ *    open(path, mode = 'r', perm = 0666, **opts) {|io| ... } -> obj
  *
  *  Creates an IO object connected to the given stream, file, or subprocess.
  *
@@ -7758,7 +7761,7 @@ check_pipe_command(VALUE filename_or_command)
  *  <b>File Opened</b>
 
  *  If +path+ does _not_ start with a pipe character (<tt>'|'</tt>),
- *  a file stream is opened with <tt>File.open(path, mode, perm, **open_opts)</tt>.
+ *  a file stream is opened with <tt>File.open(path, mode, perm, **opts)</tt>.
  *
  *  With no block given, file stream is returned:
  *
@@ -8002,7 +8005,7 @@ rb_freopen(VALUE fname, const char *mode, FILE *fp)
 /*
  *  call-seq:
  *    reopen(other_io)                 -> self
- *    reopen(path, mode = 'r', **open_opts) -> self
+ *    reopen(path, mode = 'r', **opts) -> self
  *
  *  Reassociates the stream with another stream,
  *  which may be of a different class.
@@ -8024,8 +8027,10 @@ rb_freopen(VALUE fname, const char *mode, FILE *fp)
  *    $stdin.reopen('t.txt')
  *    $stdout.reopen('t.tmp', 'w')
  *
- *  The optional keyword arguments +open_opts+ may be open options;
- *  see {\IO Open Options}[rdoc-ref:IO@Open+Options]
+ *  Optional keyword arguments +opts+ specify:
+ *
+ *  - {Open Options}[rdoc-ref:IO@Open+Options].
+ *  - {Encoding options}[rdoc-ref:encoding.rdoc@Encoding+Options].
  *
  */
 
@@ -8924,7 +8929,7 @@ rb_io_make_open_file(VALUE obj)
 
 /*
  *  call-seq:
- *    IO.new(fd, mode = 'r', **open_opts) -> io
+ *    IO.new(fd, mode = 'r', **opts) -> io
  *
  *  Creates and returns a new \IO object (file stream) from a file descriptor.
  *
@@ -8944,8 +8949,12 @@ rb_io_make_open_file(VALUE obj)
  *    IO.new(fd, 'w')         # => #<IO:fd 3>
  *    IO.new(fd, File::WRONLY) # => #<IO:fd 3>
  *
- *  Optional argument +open_opts+ must specify valid open options
- *  see {IO Open Options}[rdoc-ref:IO@Open+Options]:
+ *  Optional keyword arguments +opts+ specify:
+ *
+ *  - {Open Options}[rdoc-ref:IO@Open+Options].
+ *  - {Encoding options}[rdoc-ref:encoding.rdoc@Encoding+Options].
+ *
+ *  Examples:
  *
  *    IO.new(fd, internal_encoding: nil) # => #<IO:fd 3>
  *    IO.new(fd, autoclose: true)        # => #<IO:fd 3>
@@ -9056,7 +9065,7 @@ rb_io_set_encoding_by_bom(VALUE io)
 
 /*
  *  call-seq:
- *    File.new(path, mode = 'r', perm = 0666, **open_opts) -> file
+ *    File.new(path, mode = 'r', perm = 0666, **opts) -> file
  *
  *  Opens the file at the given +path+ according to the given +mode+;
  *  creates and returns a new \File object for that file.
@@ -9082,8 +9091,12 @@ rb_io_set_encoding_by_bom(VALUE io)
  *    File.new('t.tmp', File::CREAT, 0644)
  *    File.new('t.tmp', File::CREAT, 0444)
  *
- *  Optional argument +open_opts+ must specify valid open options
- *  see {IO Open Options}[rdoc-ref:IO@Open+Options]:
+ *  Optional keyword arguments +opts+ specify:
+ *
+ *  - {Open Options}[rdoc-ref:IO@Open+Options].
+ *  - {Encoding options}[rdoc-ref:encoding.rdoc@Encoding+Options].
+ *
+ *  Examples:
  *
  *    File.new('t.tmp', autoclose: true)
  *    File.new('t.tmp', internal_encoding: nil)
@@ -9125,7 +9138,7 @@ rb_io_s_new(int argc, VALUE *argv, VALUE klass)
 
 /*
  *  call-seq:
- *    IO.for_fd(fd, mode = 'r', **open_opts) -> io
+ *    IO.for_fd(fd, mode = 'r', **opts) -> io
  *
  *  Synonym for IO.new.
  *
@@ -9757,8 +9770,12 @@ static VALUE argf_readlines(int, VALUE *, VALUE);
  *  With arguments +sep+ and +limit+ given, combines the two behaviors;
  *  see {Line Separator and Line Limit}[rdoc-ref:IO@Line+Separator+and+Line+Limit].
  *
- *  For all forms above, trailing optional keyword arguments may be given;
- *  see {Line Options}[rdoc-ref:IO@Line+Options]:
+ *  For all forms above, optional keyword arguments specify:
+ *
+ *  - {Line Options}[rdoc-ref:IO@Line+Options].
+ *  - {Encoding options}[rdoc-ref:encoding.rdoc@Encoding+Options].
+ *
+ *  Examples:
  *
  *    $ cat t.txt | ruby -e "p readlines(chomp: true)"
  *    ["First line", "Second line", "", "Fourth line", "Fifth line"]
@@ -11002,19 +11019,15 @@ pipe_pair_close(VALUE rw)
  *
  *  If argument +enc_string+ is given, it must be a string containing one of:
  *
- *  - The name of the encoding to be used as the internal encoding.
- *  - The colon-separated names of two encodings to be used as the internal
- *    and external encodings.
- *
- *  You can view an array of the encoding names by calling method Encoding.name_list.
+ *  - The name of the encoding to be used as the external encoding.
+ *  - The colon-separated names of two encodings to be used as the external
+ *    and internal encodings.
  *
  *  If argument +int_enc+ is given, it must be an Encoding object
  *  or encoding name string that specifies the internal encoding to be used;
  *  if argument +ext_enc+ is also given, it must be an Encoding object
  *  or encoding name string that specifies the external encoding to be used.
  *
- *  You can view an array of encoding classes by calling method Encoding.list.
- *
  *  The string read from +read_io+ is tagged with the external encoding;
  *  if an internal encoding is also specified, the string is converted
  *  to, and tagged with, that encoding.
@@ -11022,9 +11035,10 @@ pipe_pair_close(VALUE rw)
  *  If any encoding is specified,
  *  optional hash arguments specify the conversion option.
  *
- *  Optional argument +opts+ must specify valid open options
- *  (see {IO Open Options}[rdoc-ref:IO@Open+Options])
- *  and/or valid encoding options (see String#encode).
+ *  Optional keyword arguments +opts+ specify:
+ *
+ *  - {Open Options}[rdoc-ref:IO@Open+Options].
+ *  - {Encoding Options}[rdoc-ref:encoding.rdoc@Encoding+Options].
  *
  *  With no block given, returns the two endpoints in an array:
  *
@@ -11239,7 +11253,7 @@ io_s_foreach(VALUE v)
  *  For both forms, command and path, the remaining arguments are the same.
  *
  *  With argument +sep+ given, parses lines as determined by that line separator
- *  (see {IO Line Separator}[rdoc-ref:IO@Line+Separator]):
+ *  (see {Line Separator}[rdoc-ref:IO@Line+Separator]):
  *
  *    File.foreach('t.txt', 'li') {|line| p line }
  *
@@ -11262,7 +11276,7 @@ io_s_foreach(VALUE v)
  *
  *  With argument +limit+ given, parses lines as determined by the default
  *  line separator and the given line-length limit
- *  (see {IO Line Limit}[rdoc-ref:IO@Line+Limit]):
+ *  (see {Line Limit}[rdoc-ref:IO@Line+Limit]):
  *
  *    File.foreach('t.txt', 7) {|line| p line }
  *
@@ -11281,12 +11295,13 @@ io_s_foreach(VALUE v)
  *  With arguments +sep+ and  +limit+ given,
  *  parses lines as determined by the given
  *  line separator and the given line-length limit
- *  (see {IO Line Separator and Line Limit}[rdoc-ref:IO@Line+Separator+and+Line+Limit]):
+ *  (see {Line Separator and Line Limit}[rdoc-ref:IO@Line+Separator+and+Line+Limit]):
  *
- *  Optional argument +opts+ specifies open options
- *  (see {IO Open Options}[rdoc-ref:IO@Open+Options])
- *  and/or valid line options
- *  (see {IO Line Options}[rdoc-ref:IO@Line+Options])
+ *  Optional keyword arguments +opts+ specify:
+ *
+ *  - {Open Options}[rdoc-ref:IO@Open+Options].
+ *  - {Encoding options}[rdoc-ref:encoding.rdoc@Encoding+Options].
+ *  - {Line Options}[rdoc-ref:IO@Line+Options].
  *
  *  Returns an Enumerator if no block is given.
  *
@@ -11356,7 +11371,7 @@ io_s_readlines(VALUE v)
  *  For both forms, command and path, the remaining arguments are the same.
  *
  *  With argument +sep+ given, parses lines as determined by that line separator
- *  (see {IO Line Separator}[rdoc-ref:IO@Line+Separator]):
+ *  (see {Line Separator}[rdoc-ref:IO@Line+Separator]):
  *
  *    # Ordinary separator.
  *    IO.readlines('t.txt', 'li')
@@ -11370,7 +11385,7 @@ io_s_readlines(VALUE v)
  *
  *  With argument +limit+ given, parses lines as determined by the default
  *  line separator and the given line-length limit
- *  (see {IO Line Limit}[rdoc-ref:IO@Line+Limit]):
+ *  (see {Line Limit}[rdoc-ref:IO@Line+Limit]):
  *
  *    IO.readlines('t.txt', 7)
  *    # => ["First l", "ine\n", "Second ", "line\n", "\n", "Third l", "ine\n", "Fourth ", "line\n"]
@@ -11378,12 +11393,13 @@ io_s_readlines(VALUE v)
  *  With arguments +sep+ and  +limit+ given,
  *  parses lines as determined by the given
  *  line separator and the given line-length limit
- *  (see {IO Line Separator and Line Limit}[rdoc-ref:IO@Line+Separator+and+Line+Limit]):
+ *  (see {Line Separator and Line Limit}[rdoc-ref:IO@Line+Separator+and+Line+Limit]):
+ *
+ *  Optional keyword arguments +opts+ specify:
  *
- *  Optional argument +opts+ specifies open options
- *  (see {IO Open Options}[rdoc-ref:IO@Open+Options])
- *  and/or valid line options
- *  (see {IO Line Options}[rdoc-ref:IO@Line+Options])
+ *  - {Open Options}[rdoc-ref:IO@Open+Options].
+ *  - {Encoding options}[rdoc-ref:encoding.rdoc@Encoding+Options].
+ *  - {Line Options}[rdoc-ref:IO@Line+Options].
  *
  */
 
@@ -11426,8 +11442,8 @@ seek_before_access(VALUE argp)
 
 /*
  *  call-seq:
- *     IO.read(command, length = nil, offset = 0, **open_opts) -> string or nil
- *     IO.read(path, length = nil, offset = 0, **open_opts)    -> string or nil
+ *     IO.read(command, length = nil, offset = 0, **opts) -> string or nil
+ *     IO.read(path, length = nil, offset = 0, **opts)    -> string or nil
  *
  *  Opens the stream, reads and returns some or all of its content,
  *  and closes the stream; returns +nil+ if no bytes were read.
@@ -11469,8 +11485,10 @@ seek_before_access(VALUE argp)
  *    IO.read('t.txt', 10, 2)   # => "rst line\nS"
  *    IO.read('t.txt', 10, 200) # => nil
  *
- *  The optional keyword arguments +open_opts+ may be open options;
- *  see {\IO Open Options}[rdoc-ref:IO@Open+Options]
+ *  Optional keyword arguments +opts+ specify:
+ *
+ *  - {Open Options}[rdoc-ref:IO@Open+Options].
+ *  - {Encoding options}[rdoc-ref:encoding.rdoc@Encoding+Options].
  *
  */
 
@@ -11606,8 +11624,8 @@ io_s_write(int argc, VALUE *argv, VALUE klass, int binary)
 
 /*
  *  call-seq:
- *    IO.write(command, data, **open_opts)             -> integer
- *    IO.write(path, data, offset = 0, **open_opts)    -> integer
+ *    IO.write(command, data, **opts)             -> integer
+ *    IO.write(path, data, offset = 0, **opts)    -> integer
  *
  *  Opens the stream, writes the given +data+ to it,
  *  and closes the stream; returns the number of bytes written.
@@ -11658,8 +11676,10 @@ io_s_write(int argc, VALUE *argv, VALUE klass, int binary)
  *    IO.write('t.tmp', 'xyz', 10) # => 3
  *    File.read('t.tmp')           # => "ab012f\u0000\u0000\u0000\u0000xyz"
  *
- *  The optional keyword arguments +open_opts+ may be open options;
- *  see {\IO Open Options}[rdoc-ref:IO@Open+Options]
+ *  Optional keyword arguments +opts+ specify:
+ *
+ *  - {Open Options}[rdoc-ref:IO@Open+Options].
+ *  - {Encoding options}[rdoc-ref:encoding.rdoc@Encoding+Options].
  *
  */
 
@@ -12740,8 +12760,8 @@ rb_io_internal_encoding(VALUE io)
  *  corresponding Encoding objects are assigned as the external
  *  and internal encodings for the stream.
  *
- *  The optional keyword arguments +enc_opts+ may be encoding options;
- *  see String#encode.
+ *  Optional keyword arguments +enc_opts+ specify
+ *  {Encoding options}[rdoc-ref:encoding.rdoc@Encoding+Options].
  *
  */