[ruby/stringio] [DOC] Doc for StringIO.getc

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

https://github.com/ruby/stringio/commit/a126fe252f

2 files changed, 37 insertions, 3 deletions

diff --git a/doc/stringio/getc.rdoc b/doc/stringio/getc.rdoc
new file mode 100644
index 0000000000..c021789c91
--- /dev/null
+++ b/doc/stringio/getc.rdoc
@@ -0,0 +1,34 @@
+Reads and returns the next character (or byte; see below) from the stream:
+
+  strio = StringIO.new('foo')
+  strio.getc # => "f"
+  strio.getc # => "o"
+  strio.getc # => "o"
+
+Returns +nil+ if at end-of-stream:
+
+  strio.eof? # => true
+  strio.getc # => nil
+
+Returns characters, not bytes:
+
+  strio = StringIO.new('тест')
+  strio.getc # => "т"
+  strio.getc # => "е"
+
+  strio = StringIO.new('こんにちは')
+  strio.getc # => "こ"
+  strio.getc # => "ん"
+
+In each of the examples above, the stream is positioned at the beginning of a character;
+in other cases that need not be true:
+
+   strio = StringIO.new('こんにちは')  # Five 3-byte characters.
+   strio.pos = 3 # => 3     # At beginning of second character; returns character.
+   strio.getc    # => "ん"
+   strio.pos = 4 # => 4     # At second byte of second character; returns byte.
+   strio.getc    # => "\x82"
+   strio.pos = 5 # => 5     # At third byte of second character; returns byte.
+   strio.getc    # => "\x93"
+
+Related: StringIO.getbyte.
diff --git a/ext/stringio/stringio.c b/ext/stringio/stringio.c
index d66768a2c5..1ceda9dcf0 100644
--- a/ext/stringio/stringio.c
+++ b/ext/stringio/stringio.c
@@ -964,10 +964,10 @@ strio_each_byte(VALUE self)
 
 /*
  * call-seq:
- *   getc -> character or nil
+ *   getc -> character, byte, or nil
+ *
+ * :include: stringio/getc.rdoc
  *
- * Reads and returns the next character from the stream;
- * see {Character IO}[rdoc-ref:IO@Character+IO].
  */
 static VALUE
 strio_getc(VALUE self)