From 3e6c6c74dd40280103e953b321e5804054707053 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Sat, 5 Feb 2022 14:05:27 -0600 Subject: [PATCH] {DOC] Enhanced RDoc for io.c (#5529) Changes parameter name from simple opts to open_opts or enc_opts when appropriate; leaves the name unchanged when more than one kind of option is allowed. --- io.c | 55 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 30 insertions(+), 25 deletions(-) diff --git a/io.c b/io.c index ae75f4fe85..1a2f9c8e8d 100644 --- a/io.c +++ b/io.c @@ -3992,7 +3992,7 @@ rb_io_gets_internal(VALUE io) * gets(sep, limit, **line_opts) -> string or nil * * Reads and returns a line from the stream - * (see {Lines}[#class-IO-label-Lines]) + * (see {Lines}[#class-IO-label-Lines]); * assigns the return value to $_. * * With no arguments given, returns the next line @@ -4220,7 +4220,8 @@ io_readlines(const struct getline_arg *arg, VALUE io) * each_line(sep, limit, **line_opts) {|line| ... } -> self * each_line -> enumerator * - * Calls the block with each remaining line read from the stream; + * Calls the block with each remaining line read from the stream + * (see {Lines}[#class-IO-label-Lines]); * does nothing if already at end-of-file; * returns +self+. * @@ -7636,8 +7637,8 @@ rb_open_file(int argc, const VALUE *argv, VALUE io) * Document-method: File::open * * call-seq: - * File.open(path, mode = 'r', perm = 0666, **opts) -> file - * File.open(path, mode = 'r', perm = 0666, **opts) {|f| ... } -> object + * File.open(path, mode = 'r', perm = 0666, **open_opts) -> file + * File.open(path, mode = 'r', perm = 0666, **open_opts) {|f| ... } -> object * * Creates a new \File object, via File.new with the given arguments. * @@ -7652,8 +7653,8 @@ rb_open_file(int argc, const VALUE *argv, VALUE io) * Document-method: IO::open * * call-seq: - * IO.open(fd, mode = 'r', **opts) -> io - * IO.open(fd, mode = 'r', **opts) {|io| ... } -> object + * IO.open(fd, mode = 'r', **open_opts) -> io + * IO.open(fd, mode = 'r', **open_opts) {|io| ... } -> object * * Creates a new \IO object, via IO.new with the given arguments. * @@ -7738,8 +7739,8 @@ check_pipe_command(VALUE filename_or_command) /* * call-seq: - * open(path, mode = 'r', perm = 0666, **opts) -> io or nil - * open(path, mode = 'r', perm = 0666, **opts) {|io| ... } -> obj + * open(path, mode = 'r', perm = 0666, **open_opts) -> io or nil + * open(path, mode = 'r', perm = 0666, **open_opts) {|io| ... } -> obj * * Creates an IO object connected to the given stream, file, or subprocess. * @@ -7754,7 +7755,7 @@ check_pipe_command(VALUE filename_or_command) * File Opened * If +path+ does _not_ start with a pipe character ('|'), - * a file stream is opened with File.open(path, mode, perm, opts). + * a file stream is opened with File.open(path, mode, perm, **open_opts). * * With no block given, file stream is returned: * @@ -7998,7 +7999,7 @@ rb_freopen(VALUE fname, const char *mode, FILE *fp) /* * call-seq: * reopen(other_io) -> self - * reopen(path, mode = 'r', **opts) -> self + * reopen(path, mode = 'r', **open_opts) -> self * * Reassociates the stream with another stream, * which may be of a different class. @@ -8020,6 +8021,9 @@ 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}[#class-IO-label-Open+Options] + * */ static VALUE @@ -8917,7 +8921,7 @@ rb_io_make_open_file(VALUE obj) /* * call-seq: - * IO.new(fd, mode = 'r', **opts) -> io + * IO.new(fd, mode = 'r', **open_opts) -> io * * Creates and returns a new \IO object (file stream) from a file descriptor. * @@ -8937,7 +8941,7 @@ rb_io_make_open_file(VALUE obj) * IO.new(fd, 'w') # => # * IO.new(fd, File::WRONLY) # => # * - * Optional argument +opts+ must specify valid open options + * Optional argument +open_opts+ must specify valid open options * see {IO Open Options}[#class-IO-label-Open+Options]: * * IO.new(fd, internal_encoding: nil) # => # @@ -9049,7 +9053,7 @@ rb_io_set_encoding_by_bom(VALUE io) /* * call-seq: - * File.new(path, mode = 'r', perm = 0666, **opts) -> file + * File.new(path, mode = 'r', perm = 0666, **open_opts) -> file * * Opens the file at the given +path+ according to the given +mode+; * creates and returns a new \File object for that file. @@ -9075,7 +9079,7 @@ rb_io_set_encoding_by_bom(VALUE io) * File.new('t.tmp', File::CREAT, 0644) * File.new('t.tmp', File::CREAT, 0444) * - * Optional argument +opts+ must specify valid open options + * Optional argument +open_opts+ must specify valid open options * see {IO Open Options}[#class-IO-label-Open+Options]: * * File.new('t.tmp', autoclose: true) @@ -9118,7 +9122,7 @@ rb_io_s_new(int argc, VALUE *argv, VALUE klass) /* * call-seq: - * IO.for_fd(fd, mode = 'r', **opts) -> io + * IO.for_fd(fd, mode = 'r', **open_opts) -> io * * Synonym for IO.new. * @@ -9710,7 +9714,8 @@ static VALUE argf_readlines(int, VALUE *, VALUE); * readlines(sep, limit, **line_opts) -> array * * Returns an array containing the lines returned by calling - * Kernel#gets until the end-of-file is reached. + * Kernel#gets until the end-of-file is reached; + * (see {Lines}[IO.html#class-IO-label-Lines]). * * With only string argument +sep+ given, * returns the remaining lines as determined by line separator +sep+, @@ -11416,8 +11421,8 @@ seek_before_access(VALUE argp) /* * call-seq: - * IO.read(command, length = nil, offset = 0, **opts) -> string or nil - * IO.read(path, length = nil, offset = 0, **opts) -> string or nil + * IO.read(command, length = nil, offset = 0, **open_opts) -> string or nil + * IO.read(path, length = nil, offset = 0, **open_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. @@ -11455,7 +11460,7 @@ 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 +opts+ may be open options; + * The optional keyword arguments +open_opts+ may be open options; * see {\IO Open Options}[#class-IO-label-Open+Options] * */ @@ -11588,8 +11593,8 @@ io_s_write(int argc, VALUE *argv, VALUE klass, int binary) /* * call-seq: - * IO.write(command, data, **opts) -> integer - * IO.write(path, data, offset = 0, **opts) -> integer + * IO.write(command, data, **open_opts) -> integer + * IO.write(path, data, offset = 0, **open_opts) -> integer * * Opens the stream, writes the given +data+ to it, * and closes the stream; returns the number of bytes written. @@ -11636,7 +11641,7 @@ 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 +opts+ may be open options; + * The optional keyword arguments +open_opts+ may be open options; * see {\IO Open Options}[#class-IO-label-Open+Options] * */ @@ -12698,8 +12703,8 @@ rb_io_internal_encoding(VALUE io) /* * call-seq: * set_encoding(ext_enc) -> self - * set_encoding(ext_enc, int_enc, **opts) -> self - * set_encoding('ext_enc:int_enc', **opts) -> self + * set_encoding(ext_enc, int_enc, **enc_opts) -> self + * set_encoding('ext_enc:int_enc', **enc_opts) -> self * * See {Encodings}[#class-IO-label-Encodings]. * @@ -12714,7 +12719,7 @@ rb_io_internal_encoding(VALUE io) * corresponding Encoding objects are assigned as the external * and internal encodings for the stream. * - * The optional keyword arguments +opts+ may be encoding options; + * The optional keyword arguments +enc_opts+ may be encoding options; * see String#encode. * */