From 487dbe1eaa2d7e79821fd4aa8fb1b33fe63c7dc6 Mon Sep 17 00:00:00 2001
From: BurdetteLamar <burdettelamar@yahoo.com>
Date: Sun, 7 Dec 2025 20:32:09 +0000
Subject: [PATCH 1/3] [DOC] Doc for StringIO#read

---
 doc/stringio/read.rdoc  | 3 +++
 ext/stringio/stringio.c | 5 +++--
 2 files changed, 6 insertions(+), 2 deletions(-)
 create mode 100644 doc/stringio/read.rdoc

diff --git a/doc/stringio/read.rdoc b/doc/stringio/read.rdoc
new file mode 100644
index 00000000..9aeff13f
--- /dev/null
+++ b/doc/stringio/read.rdoc
@@ -0,0 +1,3 @@
+Reads and returns bytes from the stream.
+
+With no arguments,
\ No newline at end of file
diff --git a/ext/stringio/stringio.c b/ext/stringio/stringio.c
index b60827fa..01850548 100644
--- a/ext/stringio/stringio.c
+++ b/ext/stringio/stringio.c
@@ -1649,9 +1649,10 @@ strio_putc(VALUE self, VALUE ch)
 
 /*
  * call-seq:
- *   strio.read([length [, outbuf]])    -> string, outbuf, or nil
+ *   read(maxlen = nil, out_string = nil) → new_string, out_string, or nil
+ *
+ * :include: stringio/read.rdoc
  *
- * See IO#read.
  */
 static VALUE
 strio_read(int argc, VALUE *argv, VALUE self)

From d1b46044813b2b97e3c17c8f97c395af4615ef26 Mon Sep 17 00:00:00 2001
From: BurdetteLamar <burdettelamar@yahoo.com>
Date: Sun, 7 Dec 2025 21:46:56 +0000
Subject: [PATCH 2/3] [DOC] Doc for StringIO.read

---
 doc/stringio/read.rdoc | 84 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 82 insertions(+), 2 deletions(-)

diff --git a/doc/stringio/read.rdoc b/doc/stringio/read.rdoc
index 9aeff13f..560f8c0b 100644
--- a/doc/stringio/read.rdoc
+++ b/doc/stringio/read.rdoc
@@ -1,3 +1,83 @@
-Reads and returns bytes from the stream.
+Reads and returns a string containing bytes read from the stream,
+beginning at the current position;
+advances the position by the count of bytes read.
 
-With no arguments,
\ No newline at end of file
+With no arguments given,
+reads all remaining bytes in the stream;
+returns a new string containing bytes read:
+
+  strio = StringIO.new('Hello') # Five 1-byte characters.
+  strio.read                    # => "Hello"
+  strio.pos                     # => 5
+  strio.read                    # => ""
+  StringIO.new('').read         # => ""
+
+With non-negative argument +maxlen+ given,
+reads +maxlen+ bytes as available;
+returns a new string containing the bytes read, or +nil+ if none:
+
+  strio.rewind
+  strio.read(3) # => "Hel"
+  strio.read(3) # => "lo"
+  strio.read(3) # => nil
+
+  russian = 'Привет' # Six 2-byte characters.
+  russian.b
+  # => "\xD0\x9F\xD1\x80\xD0\xB8\xD0\xB2\xD0\xB5\xD1\x82"
+  strio = StringIO.new(russian)
+  strio.read(6)      # => "\xD0\x9F\xD1\x80\xD0\xB8"
+  strio.read(6)      # => "\xD0\xB2\xD0\xB5\xD1\x82"
+  strio.read(6)      # => nil
+
+  japanese = 'こんにちは'
+  japanese.b
+  # => "\xE3\x81\x93\xE3\x82\x93\xE3\x81\xAB\xE3\x81\xA1\xE3\x81\xAF"
+  strio = StringIO.new(japanese)
+  strio.read(9) # => "\xE3\x81\x93\xE3\x82\x93\xE3\x81\xAB"
+  strio.read(9) # => "\xE3\x81\xA1\xE3\x81\xAF"
+  strio.read(9) # => nil
+
+With argument +max_len+ as +nil+ and string argument +out_string+ given,
+reads the remaining bytes in the stream;
+clears +out_string+ and writes the bytes into it;
+returns +out_string+:
+
+  out_string = 'Will be overwritten'
+  strio = StringIO.new('Hello')
+  strio.read(nil, out_string) # => "Hello"
+  strio.read(nil, out_string) # => ""
+
+With non-negative argument +maxlen+ and string argument +out_string+ given,
+reads the +maxlen bytes from the stream, as availble;
+clears +out_string+ and writes the bytes into it;
+returns +out_string+ if any bytes were read, or +nil+ if none:
+
+  out_string = 'Will be overwritten'
+  strio = StringIO.new('Hello')
+  strio.read(3, out_string) # => "Hel"
+  strio.read(3, out_string) # => "lo"
+  strio.read(3, out_string) # => nil
+
+  out_string = 'Will be overwritten'
+  strio = StringIO.new(russian)
+  strio.read(6, out_string) # => "При"
+  strio.read(6, out_string) # => "вет"
+  strio.read(6, out_string) # => nil
+  strio.rewind
+  russian.b
+  # => "\xD0\x9F\xD1\x80\xD0\xB8\xD0\xB2\xD0\xB5\xD1\x82"
+  strio.read(3)             # => "\xD0\x9F\xD1"
+  strio.read(3)             # => "\x80\xD0\xB8"
+
+  out_string = 'Will be overwritten'
+  strio = StringIO.new(japanese)
+  strio.read(9, out_string) # => "こんに"
+  strio.read(9, out_string) # => "ちは"
+  strio.read(9, out_string) # => nil
+  strio.rewind
+  japanese.b
+  # => "\xE3\x81\x93\xE3\x82\x93\xE3\x81\xAB\xE3\x81\xA1\xE3\x81\xAF"
+  strio.read(4)             # => "\xE3\x81\x93\xE3"
+  strio.read(4)             # => "\x82\x93\xE3\x81"
+
+Related: #gets, #readlines.

From 00a988adfa2bf521cffbaf44095d02709878d39e Mon Sep 17 00:00:00 2001
From: BurdetteLamar <burdettelamar@yahoo.com>
Date: Sun, 7 Dec 2025 21:49:16 +0000
Subject: [PATCH 3/3] [DOC] Doc for StringIO.read

---
 doc/stringio/read.rdoc | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/stringio/read.rdoc b/doc/stringio/read.rdoc
index 560f8c0b..46b9fa34 100644
--- a/doc/stringio/read.rdoc
+++ b/doc/stringio/read.rdoc
@@ -25,9 +25,9 @@ returns a new string containing the bytes read, or +nil+ if none:
   russian.b
   # => "\xD0\x9F\xD1\x80\xD0\xB8\xD0\xB2\xD0\xB5\xD1\x82"
   strio = StringIO.new(russian)
-  strio.read(6)      # => "\xD0\x9F\xD1\x80\xD0\xB8"
-  strio.read(6)      # => "\xD0\xB2\xD0\xB5\xD1\x82"
-  strio.read(6)      # => nil
+  strio.read(6) # => "\xD0\x9F\xD1\x80\xD0\xB8"
+  strio.read(6) # => "\xD0\xB2\xD0\xB5\xD1\x82"
+  strio.read(6) # => nil
 
   japanese = 'こんにちは'
   japanese.b