ruby-changes:70391
From: Burdette <ko1@a...>
Date: Tue, 21 Dec 2021 07:29:15 +0900 (JST)
Subject: [ruby-changes:70391] 6ad8cf7071 (master): [DOC] Enhanced RDoc for IO (#5307)
https://git.ruby-lang.org/ruby.git/commit/?id=6ad8cf7071 From 6ad8cf70713e6ae91a8218d4e0034ebbc1983c69 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Mon, 20 Dec 2021 16:28:58 -0600 Subject: [DOC] Enhanced RDoc for IO (#5307) Treated: #sync #sync= #fsync #fdatasync #fileno #pid #inspect #to_io --- io.c | 126 +++++++++++++++++++++++++++++++++++++++++-------------------------- 1 file changed, 77 insertions(+), 49 deletions(-) diff --git a/io.c b/io.c index 4b963ce494e..da97102b56b 100644 --- a/io.c +++ b/io.c @@ -2457,15 +2457,17 @@ rb_io_eof(VALUE io) https://github.com/ruby/ruby/blob/trunk/io.c#L2457 /* * call-seq: - * ios.sync -> true or false + * sync -> true or false * - * Returns the current ``sync mode'' of <em>ios</em>. When sync mode is - * true, all output is immediately flushed to the underlying operating - * system and is not buffered by Ruby internally. See also - * IO#fsync. + * Returns the current sync mode of the stream. + * When sync mode is true, all output is immediately flushed to the underlying + * operating system and is not buffered by Ruby internally. See also #fsync. + * + * f = File.open('t.tmp', 'w') + * f.sync # => false + * f.sync = true + * f.sync # => true * - * f = File.new("testfile") - * f.sync #=> false */ static VALUE @@ -2482,15 +2484,26 @@ rb_io_sync(VALUE io) https://github.com/ruby/ruby/blob/trunk/io.c#L2484 /* * call-seq: - * ios.sync = boolean -> boolean + * sync = boolean -> boolean * - * Sets the ``sync mode'' to <code>true</code> or <code>false</code>. - * When sync mode is true, all output is immediately flushed to the - * underlying operating system and is not buffered internally. Returns - * the new state. See also IO#fsync. + * Sets the _sync_ _mode_ for the stream to the given value; + * returns the given value. + * + * Values for the sync mode: + * + * - +true+: All output is immediately flushed to the + * underlying operating system and is not buffered internally. + * - +false+: Output may be buffered internally. + * + * Example; + * + * f = File.open('t.tmp', 'w') + * f.sync # => false + * f.sync = true + * f.sync # => true + * + * Related: IO#fsync. * - * f = File.new("testfile") - * f.sync = true */ static VALUE @@ -2511,15 +2524,20 @@ rb_io_set_sync(VALUE io, VALUE sync) https://github.com/ruby/ruby/blob/trunk/io.c#L2524 /* * call-seq: - * ios.fsync -> 0 or nil + * fsync -> 0 * - * Immediately writes all buffered data in <em>ios</em> to disk. - * Note that #fsync differs from using IO#sync=. The latter ensures - * that data is flushed from Ruby's buffers, but does not guarantee - * that the underlying operating system actually writes it to disk. + * Immediately writes to disk all data buffered in the stream, + * via the operating system's <tt>fsync(2)</tt>. + + * Note this difference: + * + * - IO#sync=: Ensures that data is flushed from the stream's internal buffers, + * but does not guarantee that the operating system actually writes the data to disk. + * - IO#fsync: Ensures both that data is flushed from internal buffers, + * and that data is written to disk. + * + * Raises an exception if the operating system does not support <tt>fsync(2)</tt>. * - * NotImplementedError is raised - * if the underlying operating system does not support <em>fsync(2)</em>. */ static VALUE @@ -2562,13 +2580,13 @@ nogvl_fdatasync(void *ptr) https://github.com/ruby/ruby/blob/trunk/io.c#L2580 /* * call-seq: - * ios.fdatasync -> 0 or nil + * fdatasync -> 0 * - * Immediately writes all buffered data in <em>ios</em> to disk. + * Immediately writes to disk all data buffered in the stream, + * via the operating system's: <tt>fdatasync(2)</tt>, if supported, + * otherwise via <tt>fsync(2)</tt>, if supported; + * otherwise raises an exception. * - * If the underlying operating system does not support <em>fdatasync(2)</em>, - * IO#fsync is called instead (which might raise a - * NotImplementedError). */ static VALUE @@ -2594,14 +2612,17 @@ rb_io_fdatasync(VALUE io) https://github.com/ruby/ruby/blob/trunk/io.c#L2612 /* * call-seq: - * ios.fileno -> integer - * ios.to_i -> integer + * fileno -> integer * - * Returns an integer representing the numeric file descriptor for - * <em>ios</em>. + * Returns the integer file descriptor for the stream: + * + * $stdin.fileno # => 0 + * $stdout.fileno # => 1 + * $stderr.fileno # => 2 + * File.open('t.txt').fileno # => 10 + * + * IO#to_i is an alias for IO#fileno. * - * $stdin.fileno #=> 0 - * $stdout.fileno #=> 1 */ static VALUE @@ -2630,22 +2651,24 @@ rb_io_descriptor(VALUE io) https://github.com/ruby/ruby/blob/trunk/io.c#L2651 /* * call-seq: - * ios.pid -> integer + * pid -> integer or nil * - * Returns the process ID of a child process associated with - * <em>ios</em>. This will be set by IO.popen. + * Returns the process ID of a child process associated with the stream, + * which will have been set by IO#popen, or +nil+ if the stream was not + * created by IO#popen: * - * pipe = IO.popen("-") - * if pipe - * $stderr.puts "In parent, child pid is #{pipe.pid}" - * else - * $stderr.puts "In child, pid is #{$$}" - * end + * pipe = IO.popen("-") + * if pipe + * $stderr.puts "In parent, child pid is #{pipe.pid}" + * else + * $stderr.puts "In child, pid is #{$$}" + * end * - * <em>produces:</em> + * Output: + * + * In child, pid is 26209 + * In parent, child pid is 26209 * - * In child, pid is 26209 - * In parent, child pid is 26209 */ static VALUE @@ -2661,10 +2684,14 @@ rb_io_pid(VALUE io) https://github.com/ruby/ruby/blob/trunk/io.c#L2684 /* - * call-seq: - * ios.inspect -> string + * call-seq: + * inspect -> string + * + * Returns a string representation of +self+: + * + * f = File.open('t.txt') + * f.inspect # => "#<File:t.txt>" * - * Return a string describing this IO object. */ static VALUE @@ -2698,9 +2725,10 @@ rb_io_inspect(VALUE obj) https://github.com/ruby/ruby/blob/trunk/io.c#L2725 /* * call-seq: - * ios.to_io -> ios + * to_io -> self + * + * Returns +self+. * - * Returns <em>ios</em>. */ static VALUE -- cgit v1.2.1 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/