mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
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
GitHub
parent
344f775eff
commit
bec3a1f15a
Notes:
git
2022-02-19 07:18:18 +09:00
Merged-By: BurdetteLamar <BurdetteLamar@Yahoo.com>
1 changed files with 81 additions and 61 deletions
142
io.c
142
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.
|
||||
*
|
||||
* <b>Forked \Process</b>
|
||||
*
|
||||
|
|
@ -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)
|
|||
* <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)
|
|||
/*
|
||||
* 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: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)
|
|||
|
||||
/*
|
||||
* 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].
|
||||
*
|
||||
*/
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue