ruby-changes:71211
From: Burdette <ko1@a...>
Date: Sat, 19 Feb 2022 07:18:11 +0900 (JST)
Subject: [ruby-changes:71211] bec3a1f15a (master): Enhanced RDoc for io.c (#5573)
https://git.ruby-lang.org/ruby.git/commit/?id=bec3a1f15a From bec3a1f15a7608ccf7b4e6eed783bf9c4c9aeb74 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Fri, 18 Feb 2022 16:17:51 -0600 Subject: 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. --- io.c | 142 ++++++++++++++++++++++++++++++++++++++----------------------------- 1 file 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) https://github.com/ruby/ruby/blob/trunk/io.c#L4042 * 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); https://github.com/ruby/ruby/blob/trunk/io.c#L4181 * - 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) https://github.com/ruby/ruby/blob/trunk/io.c#L4299 * - 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); https://github.com/ruby/ruby/blob/trunk/io.c#L7407 * 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) https://github.com/ruby/ruby/blob/trunk/io.c#L7643 * 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) https://github.com/ruby/ruby/blob/trunk/io.c#L7659 * 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) https://github.com/ruby/ruby/blob/trunk/io.c#L7745 /* * 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) https://github.com/ruby/ruby/blob/trunk/io.c#L7761 * <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) https://github.com/ruby/ruby/blob/trunk/io.c#L8005 /* * 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) https://github.com/ruby/ruby/blob/trunk/io.c#L8027 * $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) https://github.com/ruby/ruby/blob/trunk/io.c#L8929 /* * 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) https://github.com/ruby/ruby/blob/trunk/io.c#L8949 * 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) https://github.com/ruby/ruby/blob/trunk/io.c#L9065 /* * 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) https://github.com/ruby/ruby/blob/trunk/io.c#L9091 * 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) https://github.com/ruby/ruby/blob/trunk/io.c#L9138 /* * 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); https://github.com/ruby/ruby/blob/trunk/io.c#L9770 * 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) https://github.com/ruby/ruby/blob/trunk/io.c#L11019 * * 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) https://github.com/ruby/ruby/blob/trunk/io.c#L11035 * If any encoding is specified, (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/