From 8251cc129cfecb18561602a12f56e1fcaf2f05dd Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Mon, 10 Oct 2022 10:57:05 -0500 Subject: [PATCH 1/4] Enhanced RDoc for StringIO --- ext/stringio/stringio.c | 62 +++++++++++++++++++++++++++++++++-------- 1 file changed, 51 insertions(+), 11 deletions(-) diff --git a/ext/stringio/stringio.c b/ext/stringio/stringio.c index 9ba2cd92..16895694 100644 --- a/ext/stringio/stringio.c +++ b/ext/stringio/stringio.c @@ -257,9 +257,18 @@ strio_s_allocate(VALUE klass) } /* - * call-seq: StringIO.new(string=""[, mode]) + * call-seq: + * StringIO.new(string = '', mode = 'r+') -> new_stringio + * + * Returns a new \StringIO instance formed from +string+ and +mode+; + * see {Access Modes}[https://docs.ruby-lang.org/en/master/File.html#class-File-label-Access+Modes]: + * + * strio = StringIO.new # => # + * strio.close * - * Creates new StringIO instance from with _string_ and _mode_. + * The instance should be closed when no longer needed. + * + * Related: StringIO.open (accepts block; closes automatically). */ static VALUE strio_initialize(int argc, VALUE *argv, VALUE self) @@ -392,11 +401,24 @@ strio_finalize(VALUE self) } /* - * call-seq: StringIO.open(string=""[, mode]) {|strio| ...} + * call-seq: + * StringIO.open(string = '', mode = 'r+') {|strio| ... } + * + * Creates a new \StringIO instance formed from +string+ and +mode+; + * see {Access Modes}[https://docs.ruby-lang.org/en/master/File.html#class-File-label-Access+Modes]. + * + * With no block, returns the new instance: + * + * strio = StringIO.open # => # + * + * With a block, calls the block with the new instance + * and returns the block's value; + * closes the instance on block exit. * - * Equivalent to StringIO.new except that when it is called with a block, it - * yields with the new instance and closes it, and returns the result which - * returned from the block. + * StringIO.open {|strio| p strio } + * # => # + * + * Related: StringIO.new. */ static VALUE strio_s_open(int argc, VALUE *argv, VALUE klass) @@ -482,9 +504,17 @@ strio_unimpl(int argc, VALUE *argv, VALUE self) } /* - * call-seq: strio.string -> string + * call-seq: + * string -> string + * + * Returns underlying String object: + * + * strio = StringIO.new('foo') + * strio.string # => "foo" + * strio.write('bar') + * strio.string # => "bar" * - * Returns underlying String object, the subject of IO. + * Related: StringIO#string= (assigns the underlying string). */ static VALUE strio_get_string(VALUE self) @@ -494,9 +524,16 @@ strio_get_string(VALUE self) /* * call-seq: - * strio.string = string -> string + * string = string -> string + * + * Assigns the underlying String object as +string+; + * returns +string+: + * + * strio = StringIO.new('foo') + * strio.string # => "foo" + * strio.write('bar') + * strio.string # => "bar" * - * Changes underlying String object, the subject of IO. */ static VALUE strio_set_string(VALUE self, VALUE string) @@ -514,7 +551,10 @@ strio_set_string(VALUE self, VALUE string) /* * call-seq: - * strio.close -> nil + * close -> nil + * + * Closes +self+ for both reading and writing: + * * * Closes a StringIO. The stream is unavailable for any further data * operations; an +IOError+ is raised if such an attempt is made. From d7af3a7f5a33936b03b3dcb067c94ef7aa1ec954 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Mon, 10 Oct 2022 22:27:44 +0100 Subject: [PATCH 2/4] Enhanced RDoc for StringIO --- ext/stringio/stringio.c | 93 ++++++++++++++++++++++------------------- 1 file changed, 50 insertions(+), 43 deletions(-) diff --git a/ext/stringio/stringio.c b/ext/stringio/stringio.c index 16895694..d2dc8402 100644 --- a/ext/stringio/stringio.c +++ b/ext/stringio/stringio.c @@ -507,12 +507,18 @@ strio_unimpl(int argc, VALUE *argv, VALUE self) * call-seq: * string -> string * - * Returns underlying String object: + * Returns underlying string: * - * strio = StringIO.new('foo') - * strio.string # => "foo" - * strio.write('bar') - * strio.string # => "bar" + * StringIO.open('foo') do |strio| + * p strio.string + * strio.string = 'bar' + * p strio.string + * end + * + * Output: + * + * "foo" + * "bar" * * Related: StringIO#string= (assigns the underlying string). */ @@ -526,14 +532,21 @@ strio_get_string(VALUE self) * call-seq: * string = string -> string * - * Assigns the underlying String object as +string+; + * Assigns the underlying string as +string+; * returns +string+: * - * strio = StringIO.new('foo') - * strio.string # => "foo" - * strio.write('bar') - * strio.string # => "bar" + * StringIO.open('foo') do |strio| + * p strio.string + * strio.string = 'bar' + * p strio.string + * end + * + * Output: * + * "foo" + * "bar" + * + * Related: StringIO#string (returns the underlying string). */ static VALUE strio_set_string(VALUE self, VALUE string) @@ -553,11 +566,9 @@ strio_set_string(VALUE self, VALUE string) * call-seq: * close -> nil * - * Closes +self+ for both reading and writing: - * + * Closes +self+ for both reading and writing. * - * Closes a StringIO. The stream is unavailable for any further data - * operations; an +IOError+ is raised if such an attempt is made. + * Related: StringIO#close_read, StringIO#close#write. */ static VALUE strio_close(VALUE self) @@ -569,10 +580,11 @@ strio_close(VALUE self) /* * call-seq: - * strio.close_read -> nil + * close_read -> nil * - * Closes the read end of a StringIO. Will raise an +IOError+ if the - * receiver is not readable. + * Closes +self+ for reading; closed-write setting remains unchanged. + * + * Related: StringIO#clase, StringIO#close_write. */ static VALUE strio_close_read(VALUE self) @@ -587,10 +599,11 @@ strio_close_read(VALUE self) /* * call-seq: - * strio.close_write -> nil + * close_write -> nil + * + * Closes +self+ for writing; closed-read setting remains unchanged. * - * Closes the write end of a StringIO. Will raise an +IOError+ if the - * receiver is not writeable. + * Related: StringIO#clase, StringIO#close_read. */ static VALUE strio_close_write(VALUE self) @@ -605,9 +618,10 @@ strio_close_write(VALUE self) /* * call-seq: - * strio.closed? -> true or false + * closed? -> true or false * - * Returns +true+ if the stream is completely closed, +false+ otherwise. + * Returns +true+ if +self+ is closed for both reading and writing, + * +false+ otherwise. */ static VALUE strio_closed(VALUE self) @@ -619,9 +633,9 @@ strio_closed(VALUE self) /* * call-seq: - * strio.closed_read? -> true or false + * closed_read? -> true or false * - * Returns +true+ if the stream is not readable, +false+ otherwise. + * Returns +true+ if +self+ is closed for reading, +false+ otherwise. */ static VALUE strio_closed_read(VALUE self) @@ -633,9 +647,9 @@ strio_closed_read(VALUE self) /* * call-seq: - * strio.closed_write? -> true or false + * closed_write? -> true or false * - * Returns +true+ if the stream is not writable, +false+ otherwise. + * Returns +true+ if +self+ is closed for writing, +false+ otherwise. */ static VALUE strio_closed_write(VALUE self) @@ -655,11 +669,12 @@ strio_to_read(VALUE self) /* * call-seq: - * strio.eof -> true or false - * strio.eof? -> true or false + * eof? -> true or false * - * 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. + * Returns +true+ if positioned at end-of-stream +false+ otherwise; + * see {Position}[https://docs.ruby-lang.org/en/master/File.html#class-File-label-Position]. + * + * StreamIO#eof is an alias for StreamIO#eof?. */ static VALUE strio_eof(VALUE self) @@ -1791,24 +1806,16 @@ strio_set_encoding_by_bom(VALUE self) } /* - * Pseudo I/O on String object, with interface corresponding to IO. + * \IO streams for strings, with access similar to + * {IO}[https://docs.ruby-lang.org/en/master/IO.html]; + * see {IO Streams}[https://docs.ruby-lang.org/en/master/io_streams_rdoc.html]. * - * Commonly used to simulate $stdio or $stderr + * === About the Examples * - * === Examples + * Examples on this page assume that \StringIO has been required: * * require 'stringio' * - * # Writing stream emulation - * io = StringIO.new - * io.puts "Hello World" - * io.string #=> "Hello World\n" - * - * # Reading stream emulation - * io = StringIO.new "first\nsecond\nlast\n" - * io.getc #=> "f" - * io.gets #=> "irst\n" - * io.read #=> "second\nlast\n" */ void Init_stringio(void) From f7daa8af308359dfb38843f11849152da7e085f5 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Tue, 11 Oct 2022 00:28:41 +0100 Subject: [PATCH 3/4] Enhanced RDoc for StringIO --- ext/stringio/stringio.c | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/ext/stringio/stringio.c b/ext/stringio/stringio.c index d2dc8402..fbac0728 100644 --- a/ext/stringio/stringio.c +++ b/ext/stringio/stringio.c @@ -532,7 +532,7 @@ strio_get_string(VALUE self) * call-seq: * string = string -> string * - * Assigns the underlying string as +string+; + * Assigns the underlying string as +string+, and sets position to zero; * returns +string+: * * StringIO.open('foo') do |strio| @@ -568,7 +568,9 @@ strio_set_string(VALUE self, VALUE string) * * Closes +self+ for both reading and writing. * - * Related: StringIO#close_read, StringIO#close#write. + * Raises IOError if reading or writing is attempted. + * + * Related: StringIO#close_read, StringIO#close_write. */ static VALUE strio_close(VALUE self) @@ -584,7 +586,7 @@ strio_close(VALUE self) * * Closes +self+ for reading; closed-write setting remains unchanged. * - * Related: StringIO#clase, StringIO#close_write. + * Related: StringIO#close, StringIO#close_write. */ static VALUE strio_close_read(VALUE self) @@ -603,7 +605,7 @@ strio_close_read(VALUE self) * * Closes +self+ for writing; closed-read setting remains unchanged. * - * Related: StringIO#clase, StringIO#close_read. + * Related: StringIO#close, StringIO#close_read. */ static VALUE strio_close_write(VALUE self) @@ -671,7 +673,7 @@ strio_to_read(VALUE self) * call-seq: * eof? -> true or false * - * Returns +true+ if positioned at end-of-stream +false+ otherwise; + * Returns +true+ if positioned at end-of-stream, +false+ otherwise; * see {Position}[https://docs.ruby-lang.org/en/master/File.html#class-File-label-Position]. * * StreamIO#eof is an alias for StreamIO#eof?. From 5b2e86525a46d15472b655f7d969062c75269463 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Tue, 11 Oct 2022 16:12:59 +0100 Subject: [PATCH 4/4] Enhanced RDoc for StringIO --- ext/stringio/stringio.c | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/ext/stringio/stringio.c b/ext/stringio/stringio.c index fbac0728..579aef5e 100644 --- a/ext/stringio/stringio.c +++ b/ext/stringio/stringio.c @@ -260,6 +260,8 @@ strio_s_allocate(VALUE klass) * call-seq: * StringIO.new(string = '', mode = 'r+') -> new_stringio * + * Note that +mode+ defaults to 'r' if +string+ is frozen. + * * Returns a new \StringIO instance formed from +string+ and +mode+; * see {Access Modes}[https://docs.ruby-lang.org/en/master/File.html#class-File-label-Access+Modes]: * @@ -404,6 +406,8 @@ strio_finalize(VALUE self) * call-seq: * StringIO.open(string = '', mode = 'r+') {|strio| ... } * + * Note that +mode+ defaults to 'r' if +string+ is frozen. + * * Creates a new \StringIO instance formed from +string+ and +mode+; * see {Access Modes}[https://docs.ruby-lang.org/en/master/File.html#class-File-label-Access+Modes]. * @@ -530,10 +534,10 @@ strio_get_string(VALUE self) /* * call-seq: - * string = string -> string + * string = other_string -> other_string * - * Assigns the underlying string as +string+, and sets position to zero; - * returns +string+: + * Assigns the underlying string as +other_string+, and sets position to zero; + * returns +other_string+: * * StringIO.open('foo') do |strio| * p strio.string @@ -586,6 +590,8 @@ strio_close(VALUE self) * * Closes +self+ for reading; closed-write setting remains unchanged. * + * Raises IOError if reading is attempted. + * * Related: StringIO#close, StringIO#close_write. */ static VALUE @@ -605,6 +611,8 @@ strio_close_read(VALUE self) * * Closes +self+ for writing; closed-read setting remains unchanged. * + * Raises IOError if writing is attempted. + * * Related: StringIO#close, StringIO#close_read. */ static VALUE @@ -676,6 +684,8 @@ strio_to_read(VALUE self) * Returns +true+ if positioned at end-of-stream, +false+ otherwise; * see {Position}[https://docs.ruby-lang.org/en/master/File.html#class-File-label-Position]. * + * Raises IOError if the stream is not opened for reading. + * * StreamIO#eof is an alias for StreamIO#eof?. */ static VALUE