[DOC] Enhanced RDoc for io.c (#5527)

Treats:

    IO.binread (abbreviated to be like IO.binwrite).
    IO.write
    IO.binwrite
    IO.copystream
    IO#external_encoding
    IO#internal_encoding
    IO#set_encoding

io.c

@@ -11490,44 +11490,8 @@ rb_io_s_read(int argc, VALUE *argv, VALUE io)
  *     IO.binread(command, length = nil, offset = 0) -> string or nil
  *     IO.binread(path, length = nil, offset = 0)    -> string or nil
  *
- *  Opens the stream in binary mode (mode <tt>'rb:ASCII-8BIT'</tt>),
+ *  Behaves like IO.read, except that the stream is opened in binary mode
- *  reads and returns some or all of its content,
+ *  with ASCII-8BIT encoding.
- *  and closes the stream; returns +nil+ if no bytes were read.
- *
- *  The first argument must be a string;
- *  its meaning depends on whether it starts with the pipe character (<tt>'|'</tt>):
- *
- *  - If so (and if +self+ is \IO),
- *    the rest of the string is a command to be executed as a subprocess.
- *  - Otherwise, the string is the path to a file.
- *
- *  With only argument +command+ given, executes the command in a shell,
- *  returns its entire $stdout:
- *
- *    IO.binread('| cat t.rus')
- *    # => "\xD1\x82\xD0\xB5\xD1\x81\xD1\x82"
- *
- *  With only argument +path+ given, returns the entire content
- *  of the file at the given +path+:
- *
- *    IO.binread("t.rus")
- *    # => "\xD1\x82\xD0\xB5\xD1\x81\xD1\x82"
- *
- *  For both forms, command and path, the remaining arguments are the same.
- *
- *  With argument +length+, returns +length+ bytes if available:
- *
- *    IO.binread('t.rus', 5)
- *    # => "\xD1\x82\xD0\xB5\xD1"
- *
- *  With arguments +length+ and +offset+, returns +length+ bytes
- *  if available, beginning at the given +offset+:
- *
- *    IO.binread('t.rus', 5, 2)   # => "\xD0\xB5\xD1\x81\xD1"
- *    IO.binread('t.rus', 5, 200) # => nil
- *
- *  The optional keyword arguments +opts+ may be open options;
- *  see {\IO Open Options}[#class-IO-label-Open+Options]
  *
  */
 
@@ -11624,56 +11588,57 @@ io_s_write(int argc, VALUE *argv, VALUE klass, int binary)
 
 /*
  *  call-seq:
- *     IO.write(name, string [, offset])           -> integer
+ *    IO.write(command, data, **opts)             -> integer
- *     IO.write(name, string [, offset] [, opt])   -> integer
+ *    IO.write(path, data, offset = 0, **opts)    -> integer
- *     File.write(name, string [, offset])         -> integer
- *     File.write(name, string [, offset] [, opt]) -> integer
  *
- *  Opens the file, optionally seeks to the given <i>offset</i>, writes
+ *  Opens the stream, writes the given +data+ to it,
- *  <i>string</i>, then returns the length written.  #write ensures the
+ *  and closes the stream; returns the number of bytes written.
- *  file is closed before returning.  If <i>offset</i> is not given in
- *  write mode, the file is truncated.  Otherwise, it is not truncated.
  *
- *  If +name+ starts with a pipe character (<code>"|"</code>) and the receiver
+ *  The first argument must be a string;
- *  is the IO class, a subprocess is created in the same way as Kernel#open,
+ *  its meaning depends on whether it starts with the pipe character (<tt>'|'</tt>):
- *  and its output is printed to the standard output.
- *  Consider to use File.write to disable the behavior of subprocess invocation.
  *
- *    File.write("testfile", "0123456789", 20)  #=> 10
+ *  - If so (and if +self+ is an instance of \IO),
- *    # File could contain:  "This is line one\nThi0123456789two\nThis is line three\nAnd so on...\n"
+ *    the rest of the string is a command to be executed as a subprocess.
- *    File.write("testfile", "0123456789")      #=> 10
+ *  - Otherwise, the string is the path to a file.
- *    # File would now read: "0123456789"
- *    IO.write("|tr a-z A-Z", "abc")            #=> 3
- *    # Prints "ABC" to the standard output
  *
- *  If the last argument is a hash, it specifies options for the internal
+ *  With argument +command+ given, executes the command in a shell,
- *  open().  It accepts the following keys:
+ *  passes +data+ through standard input, writes its output to $stdout,
+ *  and returns the length of the given +data+:
  *
- *  :encoding::
+ *    IO.write('| cat', 'Hello World!') # => 12
- *    string or encoding
  *
- *    Specifies the encoding of the read string.
+ *  Output:
- *    See Encoding.aliases for possible encodings.
  *
- *  :mode::
+ *    Hello World!
- *    string or integer
  *
- *    Specifies the <i>mode</i> argument for open().  It must start
+ *  With argument +path+ given, writes the given +data+ to the file
- *    with "w", "a", or "r+", otherwise it will cause an error.
+ *  at that path:
- *    See IO.new for the list of possible modes.
  *
- *  :perm::
+ *    IO.write('t.tmp', 'abc')    # => 3
- *    integer
+ *    File.read('t.tmp')          # => "abc"
  *
- *    Specifies the <i>perm</i> argument for open().
+ *  If +offset+ is zero (the default), the file is overwritten:
  *
- *  :open_args::
+ *    IO.write('t.tmp', 'A')      # => 1
- *    array
+ *    File.read('t.tmp')          # => "A"
  *
- *    Specifies arguments for open() as an array.
+ *  If +offset+ in within the file content, the file is partly overwritten:
- *    This key can not be used in combination with other keys.
+ *
+ *    IO.write('t.tmp', 'abcdef') # => 3
+ *    File.read('t.tmp')          # => "abcdef"
+ *    # Offset within content.
+ *    IO.write('t.tmp', '012', 2) # => 3
+ *    File.read('t.tmp')          # => "ab012f"
+ *
+ *  If +offset+ is outside the file content,
+ *  the file is padded with null characters <tt>"\u0000"</tt>:
+ *
+ *    IO.write('t.tmp', 'xyz', 10) # => 3
+ *    File.read('t.tmp')           # => "ab012f\u0000\u0000\u0000\u0000xyz"
+ *
+ *  The optional keyword arguments +opts+ may be open options;
+ *  see {\IO Open Options}[#class-IO-label-Open+Options]
  *
- *  See also IO.read for details about +name+ and open_args.
  */
 
 static VALUE
@@ -11684,20 +11649,12 @@ rb_io_s_write(int argc, VALUE *argv, VALUE io)
 
 /*
  *  call-seq:
- *     IO.binwrite(name, string, [offset])               -> integer
+ *    IO.binwrite(command, string, offset = 0) -> integer
- *     IO.binwrite(name, string, [offset], open_args)    -> integer
+ *    IO.binwrite(path, string, offset = 0)    -> integer
- *     File.binwrite(name, string, [offset])             -> integer
- *     File.binwrite(name, string, [offset], open_args)  -> integer
  *
- *  Same as IO.write except opening the file in binary mode and
+ *  Behaves like IO.write, except that the stream is opened in binary mode
- *  ASCII-8BIT encoding (<code>"wb:ASCII-8BIT"</code>).
+ *  with ASCII-8BIT encoding.
  *
- *  If +name+ starts with a pipe character (<code>"|"</code>) and the receiver
- *  is the IO class, a subprocess is created in the same way as Kernel#open,
- *  and its output is printed to the standard output.
- *  Consider to use File.binwrite to disable the behavior of subprocess invocation.
- *
- *  See also IO.read for details about +name+ and open_args.
  */
 
 static VALUE
@@ -12612,34 +12569,51 @@ copy_stream_finalize(VALUE arg)
 
 /*
  *  call-seq:
- *     IO.copy_stream(src, dst)
+ *    IO.copy_stream(src, dst, src_length = nil, src_offset = 0) -> integer
- *     IO.copy_stream(src, dst, copy_length)
- *     IO.copy_stream(src, dst, copy_length, src_offset)
  *
- *  IO.copy_stream copies <i>src</i> to <i>dst</i>.
+ *  Copies from the given +src+ to the given +dst+,
- *  <i>src</i> and <i>dst</i> is either a filename or an IO-like object.
+ *  returning the number of bytes copied.
- *  IO-like object for <i>src</i> should have #readpartial or #read
- *  method.  IO-like object for <i>dst</i> should have #write method.
- *  (Specialized mechanisms, such as sendfile system call, may be used
- *  on appropriate situation.)
  *
- *  This method returns the number of bytes copied.
+ *  - The given +src+ must be one of the following:
  *
- *  If optional arguments are not given,
+ *    - The path to a readable file, from which source data is to be read.
- *  the start position of the copy is
+ *    - An \IO-like object, opened for reading and capable of responding
- *  the beginning of the filename or
+ *      to method +:readpartial+ or method +:read+.
- *  the current file offset of the IO.
- *  The end position of the copy is the end of file.
  *
- *  If <i>copy_length</i> is given,
+ *  - The given +dst+ must be one of the following:
- *  No more than <i>copy_length</i> bytes are copied.
  *
- *  If <i>src_offset</i> is given,
+ *    - The path to a writable file, to which data is to be written.
- *  it specifies the start position of the copy.
+ *    - An \IO-like object, opened for writing and capable of responding
+ *      to method +:write+.
  *
- *  When <i>src_offset</i> is specified and
+ *  The examples here use file <tt>t.txt</tt> as source:
- *  <i>src</i> is an IO,
+ *
- *  IO.copy_stream doesn't move the current file offset.
+ *    File.read('t.txt')
+ *    # => "First line\nSecond line\n\nThird line\nFourth line\n"
+ *    File.read('t.txt').size # => 47
+ *
+ *  If only arguments +src+ and +dst+ are given,
+ *  the entire source stream is copied:
+ *
+ *    # Paths.
+ *    IO.copy_stream('t.txt', 't.tmp')  # => 47
+ *
+ *    # IOs (recall that a File is also an IO).
+ *    src_io = File.open('t.txt', 'r') # => #<File:t.txt>
+ *    dst_io = File.open('t.tmp', 'w') # => #<File:t.tmp>
+ *    IO.copy_stream(src_io, dst_io)   # => 47
+ *
+ *  With argument +src_length+ a non-negative integer,
+ *  no more than that many bytes are copied:
+ *
+ *    IO.copy_stream('t.txt', 't.tmp', 10) # => 10
+ *    File.read('t.tmp')                   # => "First line"
+ *
+ *  With argument +src_offset+ also given,
+ *  the source stream is read beginning at that offset:
+ *
+ *    IO.copy_stream('t.txt', 't.tmp', 11, 11) # => 11
+ *    IO.read('t.tmp')                         # => "Second line"
  *
  */
 static VALUE
@@ -12675,10 +12649,13 @@ rb_io_s_copy_stream(int argc, VALUE *argv, VALUE io)
 
 /*
  *  call-seq:
- *     io.external_encoding   -> encoding
+ *    external_encoding -> encoding or nil
+ *
+ *  Returns the Encoding object that represents the encoding of the stream,
+ *  or +nil+ if the stream is in write mode and no encoding is specified.
+ *
+ *  See {Encodings}[#class-IO-label-Encodings].
  *
- *  Returns the Encoding object that represents the encoding of the file.
- *  If _io_ is in write mode and no encoding is specified, returns +nil+.
  */
 
 static VALUE
@@ -12699,10 +12676,14 @@ rb_io_external_encoding(VALUE io)
 
 /*
  *  call-seq:
- *     io.internal_encoding   -> encoding
+ *    internal_encoding -> encoding or nil
+ *
+ *  Returns the Encoding object that represents the encoding of the internal string,
+ *  if conversion is specified,
+ *  or +nil+ otherwise.
+ *
+ *  See {Encodings}[#class-IO-label-Encodings].
  *
- *  Returns the Encoding of the internal string if conversion is
- *  specified.  Otherwise returns +nil+.
  */
 
 static VALUE
@@ -12716,21 +12697,26 @@ rb_io_internal_encoding(VALUE io)
 
 /*
  *  call-seq:
- *     io.set_encoding(ext_enc)                -> io
+ *    set_encoding(ext_enc)                   -> self
- *     io.set_encoding("ext_enc:int_enc")      -> io
+ *    set_encoding(ext_enc, int_enc, **opts)  -> self
- *     io.set_encoding(ext_enc, int_enc)       -> io
+ *    set_encoding('ext_enc:int_enc', **opts) -> self
- *     io.set_encoding("ext_enc:int_enc", opt) -> io
+ *
- *     io.set_encoding(ext_enc, int_enc, opt)  -> io
+ *  See {Encodings}[#class-IO-label-Encodings].
+ *
+ *  Argument +ext_enc+, if given, must be an Encoding object;
+ *  it is assigned as the encoding for the stream.
+ *
+ *  Argument +int_enc+, if given, must be an Encoding object;
+ *  it is assigned as the encoding for the internal string.
+ *
+ *  Argument <tt>'ext_enc:int_enc'</tt>, if given, is a string
+ *  containing two colon-separated encoding names;
+ *  corresponding Encoding objects are assigned as the external
+ *  and internal encodings for the stream.
+ *
+ *  The optional keyword arguments +opts+ may be encoding options;
+ *  see String#encode.
  *
- *  If single argument is specified, read string from io is tagged
- *  with the encoding specified.  If encoding is a colon separated two
- *  encoding names "A:B", the read string is converted from encoding A
- *  (external encoding) to encoding B (internal encoding), then tagged
- *  with B.  If two arguments are specified, those must be encoding
- *  objects or encoding names, and the first one is the external encoding, and the
- *  second one is the internal encoding.
- *  If the external encoding and the internal encoding is specified,
- *  optional hash argument specify the conversion option.
  */
 
 static VALUE