[ruby/stringio] [DOC] Doc for StringIO#gets

(https://github.com/ruby/stringio/pull/164)

https://github.com/ruby/stringio/commit/10e991e31d

2 files changed, 100 insertions, 3 deletions

diff --git a/doc/stringio/gets.rdoc b/doc/stringio/gets.rdoc
new file mode 100644
index 0000000000..892c3feb53
--- /dev/null
+++ b/doc/stringio/gets.rdoc
@@ -0,0 +1,98 @@
+Reads and returns a line from the stream;
+returns +nil+ if at end-of-stream.
+
+Side effects:
+
+- Increments stream position by the number of bytes read.
+- Assigns the return value to global variable <tt>$_</tt>.
+
+With no arguments given, reads a line using the default record separator
+(global variable <tt>$/</tt>,* whose initial value is <tt>"\n"</tt>):
+
+  strio = StringIO.new(TEXT)
+  strio.pos  # => 0
+  strio.gets # => "First line\n"
+  strio.pos  # => 11
+  $_         # => "First line\n"
+  strio.gets # => "Second line\n"
+  strio.read # => "\nFourth line\nFifth line\n"
+  strio.eof? # => true
+  strio.gets # => nil
+
+  strio = StringIO.new('тест')  # Four 2-byte characters.
+  strio.pos  # => 0
+  strio.gets # => "тест"
+  strio.pos  # => 8
+
+<b>Argument +sep+</b>
+
+With only string argument +sep+ given, reads a line using that string as the record separator:
+
+  strio = StringIO.new(TEXT)
+  strio.gets(' ') # => "First "
+  strio.gets(' ') # => "line\nSecond "
+  strio.gets(' ') # => "line\n\nFourth "
+
+<b>Argument +limit+</b>
+
+With only integer argument +limit+ given,
+reads a line using the default record separator;
+limits the size (in characters) of each line to the given limit:
+
+  strio = StringIO.new(TEXT)
+  strio.gets(10) # => "First line"
+  strio.gets(10) # => "\n"
+  strio.gets(10) # => "Second lin"
+  strio.gets(10) # => "e\n"
+
+<b>Arguments +sep+ and +limit+</b>
+
+With arguments +sep+ and +limit+ both given, honors both:
+
+  strio = StringIO.new(TEXT)
+  strio.gets(' ', 10) # => "First "
+  strio.gets(' ', 10) # => "line\nSecon"
+  strio.gets(' ', 10) # => "d "
+
+<b>Position</b>
+
+As stated above, method +gets+ reads and returns the next line in the stream.
+
+In the examples above each +strio+ object starts with its position at beginning-of-stream;
+but in other cases the position may be anywhere:
+
+  strio = StringIO.new(TEXT)
+  strio.pos = 12
+  strio.gets # => "econd line\n"
+
+The position need not be at a character boundary:
+
+  strio = StringIO.new('тест')  # Four 2-byte characters.
+  strio.pos = 2                 # At beginning of second character.
+  strio.gets # => "ест"
+  strio.pos = 3                 # In middle of second character.
+  strio.gets # => "\xB5ст"
+
+<b>Special Record Separators</b>
+
+Like some methods in class IO, method +gets+ honors two special record separators;
+see {Special Line Separators}[https://docs.ruby-lang.org/en/master/IO.html#class-IO-label-Special+Line+Separator+Values]:
+
+  strio = StringIO.new(TEXT)
+  strio.gets('')  # Read "paragraph" (up to empty line).
+  # => "First line\nSecond line\n\n"
+
+  strio = StringIO.new(TEXT)
+  strio.gets(nil) # "Slurp": read all.
+  # => "First line\nSecond line\n\nFourth line\nFifth line\n"
+
+<b>Keyword Argument +chomp+</b>
+
+With keyword argument +chomp+ given as +true+ (the default is +false+),
+removes the trailing newline (if any) from the returned line:
+
+  strio = StringIO.new(TEXT)
+  strio.gets              # => "First line\n"
+  strio.gets(chomp: true) # => "Second line"
+
+Related: StringIO.each_line.
diff --git a/ext/stringio/stringio.c b/ext/stringio/stringio.c
index 5f8dc047e8..d66768a2c5 100644
--- a/ext/stringio/stringio.c
+++ b/ext/stringio/stringio.c
@@ -1428,9 +1428,8 @@ strio_getline(struct getline_arg *arg, struct StringIO *ptr)
  *   gets(limit, chomp: false) -> string or nil
  *   gets(sep, limit, chomp: false) -> string or nil
  *
- * Reads and returns a line from the stream;
- * assigns the return value to <tt>$_</tt>;
- * see {Line IO}[rdoc-ref:IO@Line+IO].
+ * :include: stringio/gets.rdoc
+ *
  */
 static VALUE
 strio_gets(int argc, VALUE *argv, VALUE self)