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.
This commit is contained in:
Burdette Lamar 2022-02-18 16:17:51 -06:00 committed by GitHub
parent 344f775eff
commit bec3a1f15a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
Notes: git 2022-02-19 07:18:18 +09:00
Merged-By: BurdetteLamar <BurdetteLamar@Yahoo.com>

142
io.c
View File

@ -4042,8 +4042,8 @@ rb_io_gets_internal(VALUE io)
* or +nil+ if none. * or +nil+ if none.
* - But returns no more bytes than are allowed by the limit. * - But returns no more bytes than are allowed by the limit.
* *
* For all forms above, trailing optional keyword arguments may be given; * For all forms above, optional keyword arguments +line_opts+ specify
* see {Line Options}[rdoc-ref:IO@Line+Options]: * {Line Options}[rdoc-ref:IO@Line+Options]:
* *
* f = File.open('t.txt') * f = File.open('t.txt')
* # Chomp the lines. * # 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+. * - Returns lines as determined by line separator +sep+.
* - But returns no more bytes in a line than are allowed by the limit. * - 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; * For all forms above, optional keyword arguments +line_opts+ specify
* see {Line Options}[rdoc-ref:IO@Line+Options]: * {Line Options}[rdoc-ref:IO@Line+Options]:
* *
* f = File.new('t.txt') * f = File.new('t.txt')
* f.readlines(chomp: true) * 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+. * - Calls with the next line as determined by line separator +sep+.
* - But returns no more bytes than are allowed by the limit. * - But returns no more bytes than are allowed by the limit.
* *
* For all forms above, trailing optional keyword arguments may be given; * For all forms above, optional keyword arguments +line_opts+ specify
* see {Line Options}[rdoc-ref:IO@Line+Options]: * {Line Options}[rdoc-ref:IO@Line+Options]:
* *
* f = File.new('t.txt') * f = File.new('t.txt')
* f.each_line(chomp: true) {|line| p line } * f.each_line(chomp: true) {|line| p line }
@ -7407,8 +7407,11 @@ static VALUE popen_finish(VALUE port, VALUE klass);
* pipe.gets * pipe.gets
* end => "bar\n" * end => "bar\n"
* *
* The optional keyword arguments +opts+ may be {\IO open options}[rdoc-ref:IO@Open+Options] * Optional keyword arguments +opts+ specify:
* and options for Kernel#spawn. *
* - {Open options}[rdoc-ref:IO@Open+Options].
* - {Encoding options}[rdoc-ref:encoding.rdoc@Encoding+Options].
* - Options for Kernel#spawn.
* *
* <b>Forked \Process</b> * <b>Forked \Process</b>
* *
@ -7640,8 +7643,8 @@ rb_open_file(int argc, const VALUE *argv, VALUE io)
* Document-method: File::open * Document-method: File::open
* *
* call-seq: * call-seq:
* File.open(path, mode = 'r', perm = 0666, **open_opts) -> file * File.open(path, mode = 'r', perm = 0666, **opts) -> file
* File.open(path, mode = 'r', perm = 0666, **open_opts) {|f| ... } -> object * File.open(path, mode = 'r', perm = 0666, **opts) {|f| ... } -> object
* *
* Creates a new \File object, via File.new with the given arguments. * 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 * Document-method: IO::open
* *
* call-seq: * call-seq:
* IO.open(fd, mode = 'r', **open_opts) -> io * IO.open(fd, mode = 'r', **opts) -> io
* IO.open(fd, mode = 'r', **open_opts) {|io| ... } -> object * IO.open(fd, mode = 'r', **opts) {|io| ... } -> object
* *
* Creates a new \IO object, via IO.new with the given arguments. * 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: * call-seq:
* open(path, mode = 'r', perm = 0666, **open_opts) -> io or nil * open(path, mode = 'r', perm = 0666, **opts) -> io or nil
* open(path, mode = 'r', perm = 0666, **open_opts) {|io| ... } -> obj * open(path, mode = 'r', perm = 0666, **opts) {|io| ... } -> obj
* *
* Creates an IO object connected to the given stream, file, or subprocess. * 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> * <b>File Opened</b>
* If +path+ does _not_ start with a pipe character (<tt>'|'</tt>), * 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: * With no block given, file stream is returned:
* *
@ -8002,7 +8005,7 @@ rb_freopen(VALUE fname, const char *mode, FILE *fp)
/* /*
* call-seq: * call-seq:
* reopen(other_io) -> self * reopen(other_io) -> self
* reopen(path, mode = 'r', **open_opts) -> self * reopen(path, mode = 'r', **opts) -> self
* *
* Reassociates the stream with another stream, * Reassociates the stream with another stream,
* which may be of a different class. * which may be of a different class.
@ -8024,8 +8027,10 @@ rb_freopen(VALUE fname, const char *mode, FILE *fp)
* $stdin.reopen('t.txt') * $stdin.reopen('t.txt')
* $stdout.reopen('t.tmp', 'w') * $stdout.reopen('t.tmp', 'w')
* *
* The optional keyword arguments +open_opts+ may be open options; * Optional keyword arguments +opts+ specify:
* see {\IO Open Options}[rdoc-ref:IO@Open+Options] *
* - {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: * 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. * 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, 'w') # => #<IO:fd 3>
* IO.new(fd, File::WRONLY) # => #<IO:fd 3> * IO.new(fd, File::WRONLY) # => #<IO:fd 3>
* *
* Optional argument +open_opts+ must specify valid open options * Optional keyword arguments +opts+ specify:
* see {IO Open Options}[rdoc-ref:IO@Open+Options]: *
* - {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, internal_encoding: nil) # => #<IO:fd 3>
* IO.new(fd, autoclose: true) # => #<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: * 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+; * Opens the file at the given +path+ according to the given +mode+;
* creates and returns a new \File object for that file. * 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, 0644)
* File.new('t.tmp', File::CREAT, 0444) * File.new('t.tmp', File::CREAT, 0444)
* *
* Optional argument +open_opts+ must specify valid open options * Optional keyword arguments +opts+ specify:
* see {IO Open Options}[rdoc-ref:IO@Open+Options]: *
* - {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', autoclose: true)
* File.new('t.tmp', internal_encoding: nil) * File.new('t.tmp', internal_encoding: nil)
@ -9125,7 +9138,7 @@ rb_io_s_new(int argc, VALUE *argv, VALUE klass)
/* /*
* call-seq: * call-seq:
* IO.for_fd(fd, mode = 'r', **open_opts) -> io * IO.for_fd(fd, mode = 'r', **opts) -> io
* *
* Synonym for IO.new. * 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; * With arguments +sep+ and +limit+ given, combines the two behaviors;
* see {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].
* *
* For all forms above, trailing optional keyword arguments may be given; * For all forms above, optional keyword arguments specify:
* see {Line Options}[rdoc-ref:IO@Line+Options]: *
* - {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)" * $ cat t.txt | ruby -e "p readlines(chomp: true)"
* ["First line", "Second line", "", "Fourth line", "Fifth line"] * ["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: * 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 name of the encoding to be used as the external encoding.
* - The colon-separated names of two encodings to be used as the internal * - The colon-separated names of two encodings to be used as the external
* and external encodings. * and internal encodings.
*
* You can view an array of the encoding names by calling method Encoding.name_list.
* *
* If argument +int_enc+ is given, it must be an Encoding object * If argument +int_enc+ is given, it must be an Encoding object
* or encoding name string that specifies the internal encoding to be used; * 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 * 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. * 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; * The string read from +read_io+ is tagged with the external encoding;
* if an internal encoding is also specified, the string is converted * if an internal encoding is also specified, the string is converted
* to, and tagged with, that encoding. * to, and tagged with, that encoding.
@ -11022,9 +11035,10 @@ pipe_pair_close(VALUE rw)
* If any encoding is specified, * If any encoding is specified,
* optional hash arguments specify the conversion option. * optional hash arguments specify the conversion option.
* *
* Optional argument +opts+ must specify valid open options * Optional keyword arguments +opts+ specify:
* (see {IO Open Options}[rdoc-ref:IO@Open+Options]) *
* and/or valid encoding options (see String#encode). * - {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: * 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. * For both forms, command and path, the remaining arguments are the same.
* *
* With argument +sep+ given, parses lines as determined by that line separator * 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 } * 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 * With argument +limit+ given, parses lines as determined by the default
* line separator and the given line-length limit * 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 } * File.foreach('t.txt', 7) {|line| p line }
* *
@ -11281,12 +11295,13 @@ io_s_foreach(VALUE v)
* With arguments +sep+ and +limit+ given, * With arguments +sep+ and +limit+ given,
* parses lines as determined by the given * parses lines as determined by the given
* line separator and the given line-length limit * 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 * Optional keyword arguments +opts+ specify:
* (see {IO Open Options}[rdoc-ref:IO@Open+Options]) *
* and/or valid line options * - {Open Options}[rdoc-ref:IO@Open+Options].
* (see {IO Line Options}[rdoc-ref:IO@Line+Options]) * - {Encoding options}[rdoc-ref:encoding.rdoc@Encoding+Options].
* - {Line Options}[rdoc-ref:IO@Line+Options].
* *
* Returns an Enumerator if no block is given. * 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. * For both forms, command and path, the remaining arguments are the same.
* *
* With argument +sep+ given, parses lines as determined by that line separator * 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. * # Ordinary separator.
* IO.readlines('t.txt', 'li') * 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 * With argument +limit+ given, parses lines as determined by the default
* line separator and the given line-length limit * 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) * IO.readlines('t.txt', 7)
* # => ["First l", "ine\n", "Second ", "line\n", "\n", "Third l", "ine\n", "Fourth ", "line\n"] * # => ["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, * With arguments +sep+ and +limit+ given,
* parses lines as determined by the given * parses lines as determined by the given
* line separator and the given line-length limit * 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 * Optional keyword arguments +opts+ specify:
* (see {IO Open Options}[rdoc-ref:IO@Open+Options]) *
* and/or valid line options * - {Open Options}[rdoc-ref:IO@Open+Options].
* (see {IO Line Options}[rdoc-ref:IO@Line+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: * call-seq:
* IO.read(command, 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, **open_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, * Opens the stream, reads and returns some or all of its content,
* and closes the stream; returns +nil+ if no bytes were read. * 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, 2) # => "rst line\nS"
* IO.read('t.txt', 10, 200) # => nil * IO.read('t.txt', 10, 200) # => nil
* *
* The optional keyword arguments +open_opts+ may be open options; * Optional keyword arguments +opts+ specify:
* see {\IO Open Options}[rdoc-ref:IO@Open+Options] *
* - {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: * call-seq:
* IO.write(command, data, **open_opts) -> integer * IO.write(command, data, **opts) -> integer
* IO.write(path, data, offset = 0, **open_opts) -> integer * IO.write(path, data, offset = 0, **opts) -> integer
* *
* Opens the stream, writes the given +data+ to it, * Opens the stream, writes the given +data+ to it,
* and closes the stream; returns the number of bytes written. * 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 * IO.write('t.tmp', 'xyz', 10) # => 3
* File.read('t.tmp') # => "ab012f\u0000\u0000\u0000\u0000xyz" * File.read('t.tmp') # => "ab012f\u0000\u0000\u0000\u0000xyz"
* *
* The optional keyword arguments +open_opts+ may be open options; * Optional keyword arguments +opts+ specify:
* see {\IO Open Options}[rdoc-ref:IO@Open+Options] *
* - {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 * corresponding Encoding objects are assigned as the external
* and internal encodings for the stream. * and internal encodings for the stream.
* *
* The optional keyword arguments +enc_opts+ may be encoding options; * Optional keyword arguments +enc_opts+ specify
* see String#encode. * {Encoding options}[rdoc-ref:encoding.rdoc@Encoding+Options].
* *
*/ */