From bec3a1f15a7608ccf7b4e6eed783bf9c4c9aeb74 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Fri, 18 Feb 2022 16:17:51 -0600 Subject: [PATCH] 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) * 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. * * Forked \Process * @@ -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) * File Opened * If +path+ does _not_ start with a pipe character ('|'), - * a file stream is opened with File.open(path, mode, perm, **open_opts). + * a file stream is opened with File.open(path, mode, perm, **opts). * * 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.new(fd, File::WRONLY) # => # * - * 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.new(fd, autoclose: true) # => # @@ -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 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]. * */ @@ -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]. * */