https://git.ruby-lang.org/ruby.git/commit/?id=2746fd5d50

From 2746fd5d50429994b0d66bb49c2e09089beb1b3f Mon Sep 17 00:00:00 2001
From: zverok <zverok.offline@g...>
Date: Sat, 26 Oct 2019 10:03:24 +0300
Subject: Update StringIO docs:

* More explanations/examples in class docs;
* Fix links to other methods (remove <code> tag);
* Fix wording of method docs (remove *stringio*
  receiver name, as it is not rendered by modern
  RDoc);
* Add  option mention to linereading
  methods (added in 2.4);
* Several other small fixes.

diff --git a/ext/stringio/stringio.c b/ext/stringio/stringio.c
index 15e5cdd..d6db112 100644
--- a/ext/stringio/stringio.c
+++ b/ext/stringio/stringio.c
@@ -429,7 +429,7 @@ strio_nil(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/stringio/stringio.c#L429
 }
 
 /*
- * Returns *strio* itself.  Just for compatibility to IO.
+ * Returns an object itself.  Just for compatibility to IO.
  */
 static VALUE
 strio_self(VALUE self)
@@ -505,7 +505,7 @@ strio_set_string(VALUE self, VALUE string) https://github.com/ruby/ruby/blob/trunk/ext/stringio/stringio.c#L505
  * call-seq:
  *   strio.close  -> nil
  *
- * Closes strio.  The *strio* is unavailable for any further data
+ * Closes a StringIO. The stream is unavailable for any further data
  * operations; an +IOError+ is raised if such an attempt is made.
  */
 static VALUE
@@ -521,7 +521,7 @@ strio_close(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/stringio/stringio.c#L521
  *   strio.close_read    -> nil
  *
  * Closes the read end of a StringIO.  Will raise an +IOError+ if the
- * *strio* is not readable.
+ * receiver is not readable.
  */
 static VALUE
 strio_close_read(VALUE self)
@@ -539,7 +539,7 @@ strio_close_read(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/stringio/stringio.c#L539
  *   strio.close_write    -> nil
  *
  * Closes the write end of a StringIO.  Will raise an  +IOError+ if the
- * *strio* is not writeable.
+ * receiver is not writeable.
  */
 static VALUE
 strio_close_write(VALUE self)
@@ -556,7 +556,7 @@ strio_close_write(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/stringio/stringio.c#L556
  * call-seq:
  *   strio.closed?    -> true or false
  *
- * Returns +true+ if *strio* is completely closed, +false+ otherwise.
+ * Returns +true+ if the stream is completely closed, +false+ otherwise.
  */
 static VALUE
 strio_closed(VALUE self)
@@ -570,7 +570,7 @@ strio_closed(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/stringio/stringio.c#L570
  * call-seq:
  *   strio.closed_read?    -> true or false
  *
- * Returns +true+ if *strio* is not readable, +false+ otherwise.
+ * Returns +true+ if the stream is not readable, +false+ otherwise.
  */
 static VALUE
 strio_closed_read(VALUE self)
@@ -584,7 +584,7 @@ strio_closed_read(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/stringio/stringio.c#L584
  * call-seq:
  *   strio.closed_write?    -> true or false
  *
- * Returns +true+ if *strio* is not writable, +false+ otherwise.
+ * Returns +true+ if the stream is not writable, +false+ otherwise.
  */
 static VALUE
 strio_closed_write(VALUE self)
@@ -599,8 +599,8 @@ strio_closed_write(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/stringio/stringio.c#L599
  *   strio.eof     -> true or false
  *   strio.eof?    -> true or false
  *
- * Returns true if *strio* is at end of file. The stringio must be
- * opened for reading or an +IOError+ will be raised.
+ * Returns true if the stream is at the end of the data (underlying string).
+ * The stream must be opened for reading or an +IOError+ will be raised.
  */
 static VALUE
 strio_eof(VALUE self)
@@ -634,7 +634,7 @@ strio_copy(VALUE copy, VALUE orig) https://github.com/ruby/ruby/blob/trunk/ext/stringio/stringio.c#L634
  * call-seq:
  *   strio.lineno    -> integer
  *
- * Returns the current line number in *strio*. The stringio must be
+ * Returns the current line number. The stream must be
  * opened for reading. +lineno+ counts the number of times  +gets+ is
  * called, rather than the number of newlines  encountered. The two
  * values will differ if +gets+ is  called with a separator other than
@@ -660,6 +660,13 @@ strio_set_lineno(VALUE self, VALUE lineno) https://github.com/ruby/ruby/blob/trunk/ext/stringio/stringio.c#L660
     return lineno;
 }
 
+/*
+ * call-seq:
+ *   strio.binmode    -> stringio
+ *
+ * Puts stream into binary mode. See IO#binmode.
+ *
+ */
 static VALUE
 strio_binmode(VALUE self)
 {
@@ -684,7 +691,7 @@ strio_binmode(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/stringio/stringio.c#L691
  *   strio.reopen(other_StrIO)     -> strio
  *   strio.reopen(string, mode)    -> strio
  *
- * Reinitializes *strio* with the given <i>other_StrIO</i> or _string_
+ * Reinitializes the stream with the given <i>other_StrIO</i> or _string_
  * and _mode_ (see StringIO#new).
  */
 static VALUE
@@ -702,7 +709,7 @@ strio_reopen(int argc, VALUE *argv, VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/stringio/stringio.c#L709
  *   strio.pos     -> integer
  *   strio.tell    -> integer
  *
- * Returns the current offset (in bytes) of *strio*.
+ * Returns the current offset (in bytes).
  */
 static VALUE
 strio_get_pos(VALUE self)
@@ -714,7 +721,7 @@ strio_get_pos(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/stringio/stringio.c#L721
  * call-seq:
  *   strio.pos = integer    -> integer
  *
- * Seeks to the given position (in bytes) in *strio*.
+ * Seeks to the given position (in bytes).
  */
 static VALUE
 strio_set_pos(VALUE self, VALUE pos)
@@ -732,7 +739,7 @@ strio_set_pos(VALUE self, VALUE pos) https://github.com/ruby/ruby/blob/trunk/ext/stringio/stringio.c#L739
  * call-seq:
  *   strio.rewind    -> 0
  *
- * Positions *strio* to the beginning of input, resetting
+ * Positions the stream to the beginning of input, resetting
  * +lineno+ to zero.
  */
 static VALUE
@@ -900,7 +907,7 @@ strio_extend(struct StringIO *ptr, long pos, long len) https://github.com/ruby/ruby/blob/trunk/ext/stringio/stringio.c#L907
  * call-seq:
  *   strio.ungetc(string)   -> nil
  *
- * Pushes back one character (passed as a parameter) onto *strio*
+ * Pushes back one character (passed as a parameter)
  * such that a subsequent buffered read will return it.  There is no
  * limitation for multiple pushbacks including pushing back behind the
  * beginning of the buffer string.
@@ -1047,7 +1054,7 @@ strio_each_char(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/stringio/stringio.c#L1054
 }
 
 /*
- *  This is a deprecated alias for <code>each_char</code>.
+ *  This is a deprecated alias for #each_char.
  */
 static VALUE
 strio_chars(VALUE self)
@@ -1091,7 +1098,7 @@ strio_each_codepoint(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/stringio/stringio.c#L1098
 }
 
 /*
- *  This is a deprecated alias for <code>each_codepoint</code>.
+ *  This is a deprecated alias for #each_codepoint.
  */
 static VALUE
 strio_codepoints(VALUE self)
@@ -1281,9 +1288,9 @@ strio_getline(struct getline_arg *arg, struct StringIO *ptr) https://github.com/ruby/ruby/blob/trunk/ext/stringio/stringio.c#L1288
 
 /*
  * call-seq:
- *   strio.gets(sep=$/)     -> string or nil
- *   strio.gets(limit)      -> string or nil
- *   strio.gets(sep, limit) -> string or nil
+ *   strio.gets(sep=$/, chomp: false)     -> string or nil
+ *   strio.gets(limit, chomp: false)      -> string or nil
+ *   strio.gets(sep, limit, chomp: false) -> string or nil
  *
  * See IO#gets.
  */
@@ -1305,9 +1312,9 @@ strio_gets(int argc, VALUE *argv, VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/stringio/stringio.c#L1312
 
 /*
  * call-seq:
- *   strio.readline(sep=$/)     -> string
- *   strio.readline(limit)      -> string or nil
- *   strio.readline(sep, limit) -> string or nil
+ *   strio.readline(sep=$/, chomp: false)     -> string
+ *   strio.readline(limit, chomp: false)      -> string or nil
+ *   strio.readline(sep, limit, chomp: false) -> string or nil
  *
  * See IO#readline.
  */
@@ -1321,15 +1328,15 @@ strio_readline(int argc, VALUE *argv, VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/stringio/stringio.c#L1328
 
 /*
  * call-seq:
- *   strio.each(sep=$/) {|line| block }         -> strio
- *   strio.each(limit) {|line| block }          -> strio
- *   strio.each(sep, limit) {|line| block }     -> strio
- *   strio.each(...)                            -> anEnumerator
+ *   strio.each(sep=$/, chomp: false) {|line| block }         -> strio
+ *   strio.each(limit, chomp: false) {|line| block }          -> strio
+ *   strio.each(sep, limit, chomp: false) {|line| block }     -> strio
+ *   strio.each(...)                                          -> anEnumerator
  *
- *   strio.each_line(sep=$/) {|line| block }    -> strio
- *   strio.each_line(limit) {|line| block }     -> strio
- *   strio.each_line(sep,limit) {|line| block } -> strio
- *   strio.each_line(...)                       -> anEnumerator
+ *   strio.each_line(sep=$/, chomp: false) {|line| block }     -> strio
+ *   strio.each_line(limit, chomp: false) {|line| block }      -> strio
+ *   strio.each_line(sep, limit, chomp: false) {|line| block } -> strio
+ *   strio.each_line(...)                                      -> anEnumerator
  *
  * See IO#each.
  */
@@ -1353,7 +1360,7 @@ strio_each(int argc, VALUE *argv, VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/stringio/stringio.c#L1360
 }
 
 /*
- *  This is a deprecated alias for <code>each_line</code>.
+ *  This is a deprecated alias for #each_line.
  */
 static VALUE
 strio_lines(int argc, VALUE *argv, VALUE self)
@@ -1366,9 +1373,9 @@ strio_lines(int argc, VALUE *argv, VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/stringio/stringio.c#L1373
 
 /*
  * call-seq:
- *   strio.readlines(sep=$/)    ->   array
- *   strio.readlines(limit)     ->   array
- *   strio.readlines(sep,limit) ->   array
+ *   strio.readlines(sep=$/, chomp: false)     ->   array
+ *   strio.readlines(limit, chomp: false)      ->   array
+ *   strio.readlines(sep, limit, chomp: false) ->   (... truncated)

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/