* ext/stringio/stringio.c: add rdoc.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_1_8@8153 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 284 insertions, 0 deletions

diff --git a/ext/stringio/stringio.c b/ext/stringio/stringio.c
index 6c5f7e0d83..24d0bd1e91 100644
--- a/ext/stringio/stringio.c
+++ b/ext/stringio/stringio.c
@@ -187,6 +187,13 @@ strio_s_allocate(klass)
     return Data_Wrap_Struct(klass, strio_mark, strio_free, 0);
 }
 
+/*
+ * call-seq: StringIO.open(string=""[, mode]) {|strio| ...}
+ *
+ * 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.
+ */
 static VALUE
 strio_s_open(argc, argv, klass)
     int argc;
@@ -198,6 +205,11 @@ strio_s_open(argc, argv, klass)
     return rb_ensure(rb_yield, obj, strio_finalize, obj);
 }
 
+/*
+ * call-seq: StringIO.new(string=""[, mode])
+ *
+ * Creates new StringIO instance from with _string_ and _mode_.
+ */
 static VALUE
 strio_initialize(argc, argv, self)
     int argc;
@@ -256,6 +268,9 @@ strio_finalize(self)
     return self;
 }
 
+/*
+ * Returns +false+.  Just for compatibility to IO.
+ */
 static VALUE
 strio_false(self)
     VALUE self;
@@ -264,6 +279,9 @@ strio_false(self)
     return Qfalse;
 }
 
+/*
+ * Returns +nil+.  Just for compatibility to IO.
+ */
 static VALUE
 strio_nil(self)
     VALUE self;
@@ -272,6 +290,9 @@ strio_nil(self)
     return Qnil;
 }
 
+/*
+ * Returns *strio* itself.  Just for compatibility to IO.
+ */
 static VALUE
 strio_self(self)
     VALUE self;
@@ -280,6 +301,9 @@ strio_self(self)
     return self;
 }
 
+/*
+ * Returns 0.  Just for compatibility to IO.
+ */
 static VALUE
 strio_0(self)
     VALUE self;
@@ -288,6 +312,9 @@ strio_0(self)
     return INT2FIX(0);
 }
 
+/*
+ * Returns the argument unchanged.  Just for compatibility to IO.
+ */
 static VALUE
 strio_first(self, arg)
     VALUE self, arg;
@@ -296,6 +323,9 @@ strio_first(self, arg)
     return arg;
 }
 
+/*
+ * Raises NotImplementedError.
+ */
 static VALUE
 strio_unimpl(argc, argv, self)
     int argc;
@@ -307,6 +337,11 @@ strio_unimpl(argc, argv, self)
     return Qnil;		/* not reached */
 }
 
+/*
+ * call-seq: strio.string     -> string
+ *
+ * Returns underlying String object, the subject of IO.
+ */
 static VALUE
 strio_get_string(self)
     VALUE self;
@@ -314,6 +349,12 @@ strio_get_string(self)
     return StringIO(self)->string;
 }
 
+/*
+ * call-seq:
+ *   strio.string = string  -> string
+ *
+ * Changes underlying String object, the subject of IO.
+ */
 static VALUE
 strio_set_string(self, string)
     VALUE self, string;
@@ -331,6 +372,13 @@ strio_set_string(self, string)
     return ptr->string = string;
 }
 
+/*
+ * call-seq:
+ *   strio.close  -> nil
+ *
+ * Closes strio.  The *strio* is unavailable for any further data 
+ * operations; an +IOError+ is raised if such an attempt is made.
+ */
 static VALUE
 strio_close(self)
     VALUE self;
@@ -344,6 +392,13 @@ strio_close(self)
     return Qnil;
 }
 
+/*
+ * call-seq:
+ *   strio.close_read    -> nil
+ *
+ * Closes the read end of a StringIO.  Will raise an +IOError+ if the
+ * *strio* is not readable.
+ */
 static VALUE
 strio_close_read(self)
     VALUE self;
@@ -358,6 +413,13 @@ strio_close_read(self)
     return Qnil;
 }
 
+/*
+ * call-seq:
+ *   strio.close_write    -> nil
+ *
+ * Closes the write end of a StringIO.  Will raise an  +IOError+ if the
+ * *strio* is not writeable.
+ */
 static VALUE
 strio_close_write(self)
     VALUE self;
@@ -372,6 +434,12 @@ strio_close_write(self)
     return Qnil;
 }
 
+/*
+ * call-seq:
+ *   strio.closed?    -> true or false
+ *
+ * Returns +true+ if *strio* is completely closed, +false+ otherwise.
+ */
 static VALUE
 strio_closed(self)
     VALUE self;
@@ -381,6 +449,12 @@ strio_closed(self)
     return Qtrue;
 }
 
+/*
+ * call-seq:
+ *   strio.closed_read?    -> true or false
+ *
+ * Returns +true+ if *strio* is not readable, +false+ otherwise.
+ */
 static VALUE
 strio_closed_read(self)
     VALUE self;
@@ -390,6 +464,12 @@ strio_closed_read(self)
     return Qtrue;
 }
 
+/*
+ * call-seq:
+ *   strio.closed_write?    -> true or false
+ *
+ * Returns +true+ if *strio* is not writable, +false+ otherwise.
+ */
 static VALUE
 strio_closed_write(self)
     VALUE self;
@@ -399,6 +479,14 @@ strio_closed_write(self)
     return Qtrue;
 }
 
+/*
+ * call-seq:
+ *   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.
+ */
 static VALUE
 strio_eof(self)
     VALUE self;
@@ -408,6 +496,7 @@ strio_eof(self)
     return Qtrue;
 }
 
+/* :nodoc: */
 static VALUE
 strio_copy(copy, orig)
     VALUE copy, orig;
@@ -426,6 +515,16 @@ strio_copy(copy, orig)
     return copy;
 }
 
+/*
+ * call-seq:
+ *   strio.lineno    -> integer
+ *
+ * Returns the current line number in *strio*. The stringio 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
+ * newline.  See also the  <code>$.</code> variable.
+ */
 static VALUE
 strio_get_lineno(self)
     VALUE self;
@@ -433,6 +532,13 @@ strio_get_lineno(self)
     return LONG2NUM(StringIO(self)->lineno);
 }
 
+/*
+ * call-seq:
+ *   strio.lineno = integer    -> integer
+ *
+ * Manually sets the current line number to the given value.
+ * <code>$.</code> is updated only on the next read.
+ */
 static VALUE
 strio_set_lineno(self, lineno)
     VALUE self, lineno;
@@ -441,14 +547,26 @@ strio_set_lineno(self, lineno)
     return lineno;
 }
 
+/* call-seq: strio.binmode -> true */
 #define strio_binmode strio_self
 
+/* call-seq: strio.fcntl */
 #define strio_fcntl strio_unimpl
 
+/* call-seq: strio.flush -> strio */
 #define strio_flush strio_self
 
+/* call-seq: strio.fsync -> 0 */
 #define strio_fsync strio_0
 
+/*
+ * call-seq:
+ *   strio.reopen(other_StrIO)     -> strio
+ *   strio.reopen(string, mode)    -> strio
+ *
+ * Reinitializes *strio* with the given <i>other_StrIO</i> or _string_ 
+ * and _mode_ (see StringIO#new).
+ */
 static VALUE
 strio_reopen(argc, argv, self)
     int argc;
@@ -462,6 +580,13 @@ strio_reopen(argc, argv, self)
     return strio_initialize(argc, argv, self);
 }
 
+/*
+ * call-seq:
+ *   strio.pos     -> integer
+ *   strio.tell    -> integer
+ *
+ * Returns the current offset (in bytes) of *strio*.
+ */
 static VALUE
 strio_get_pos(self)
     VALUE self;
@@ -469,6 +594,12 @@ strio_get_pos(self)
     return LONG2NUM(StringIO(self)->pos);
 }
 
+/*
+ * call-seq:
+ *   strio.pos = integer    -> integer
+ *
+ * Seeks to the given position (in bytes) in *strio*.
+ */
 static VALUE
 strio_set_pos(self, pos)
     VALUE self;
@@ -484,6 +615,13 @@ strio_set_pos(self, pos)
     return pos;
 }
 
+/*
+ * call-seq:
+ *   strio.rewind    -> 0
+ *
+ * Positions *strio* to the beginning of input, resetting
+ * +lineno+ to zero.
+ */
 static VALUE
 strio_rewind(self)
     VALUE self;
@@ -495,6 +633,13 @@ strio_rewind(self)
     return INT2FIX(0);
 }
 
+/*
+ * call-seq:
+ *   strio.seek(amount, whence=SEEK_SET) -> 0
+ *
+ * Seeks to a given offset _amount_ in the stream according to
+ * the value of _whence_ (see IO#seek).
+ */
 static VALUE
 strio_seek(argc, argv, self)
     int argc;
@@ -527,6 +672,12 @@ strio_seek(argc, argv, self)
     return INT2FIX(0);
 }
 
+/*
+ * call-seq:
+ *   strio.sync    -> true
+ *
+ * Returns +true+ always.
+ */
 static VALUE
 strio_get_sync(self)
     VALUE self;
@@ -535,10 +686,17 @@ strio_get_sync(self)
     return Qtrue;
 }
 
+/* call-seq: strio.sync = boolean -> boolean */
 #define strio_set_sync strio_first
 
 #define strio_tell strio_get_pos
 
+/*
+ * call-seq:
+ *   strio.each_byte {|byte| block }  -> strio
+ *
+ * See IO#each_byte.
+ */
 static VALUE
 strio_each_byte(self)
     VALUE self;
@@ -551,6 +709,12 @@ strio_each_byte(self)
     return Qnil;
 }
 
+/*
+ * call-seq:
+ *   strio.getc   -> fixnum or nil
+ *
+ * See IO#getc.
+ */
 static VALUE
 strio_getc(self)
     VALUE self;
@@ -584,6 +748,16 @@ strio_extend(ptr, pos, len)
     }
 }
 
+/*
+ * call-seq:
+ *   strio.ungetc(integer)   -> nil
+ *
+ * Pushes back one character (passed as a parameter) onto *strio*
+ * such that a subsequent buffered read will return it.  Pushing back 
+ * behind the beginning of the buffer string is not possible.  Nothing
+ * will be done if such an attempt is made.
+ * In other case, there is no limitation for multiple pushbacks.
+ */
 static VALUE
 strio_ungetc(self, ch)
     VALUE self, ch;
@@ -606,6 +780,12 @@ strio_ungetc(self, ch)
     return Qnil;
 }
 
+/*
+ * call-seq:
+ *   strio.readchar   => fixnum
+ *
+ * See IO#readchar.
+ */
 static VALUE
 strio_readchar(self)
     VALUE self;
@@ -733,6 +913,12 @@ strio_getline(argc, argv, ptr)
     return str;
 }
 
+/*
+ * call-seq:
+ *   strio.gets(sep_string=$/)   -> string or nil
+ *
+ * See IO#gets.
+ */
 static VALUE
 strio_gets(argc, argv, self)
     int argc;
@@ -745,6 +931,12 @@ strio_gets(argc, argv, self)
     return str;
 }
 
+/*
+ * call-seq:
+ *   strio.readline(sep_string=$/)   -> string
+ *
+ * See IO#readline.
+ */
 static VALUE
 strio_readline(argc, argv, self)
     int argc;
@@ -756,6 +948,13 @@ strio_readline(argc, argv, self)
     return line;
 }
 
+/*
+ * call-seq:
+ *   strio.each(sep_string=$/)      {|line| block }  => strio
+ *   strio.each_line(sep_string=$/) {|line| block }  => strio
+ *
+ * See IO#each.
+ */
 static VALUE
 strio_each(argc, argv, self)
     int argc;
@@ -771,6 +970,12 @@ strio_each(argc, argv, self)
     return self;
 }
 
+/*
+ * call-seq:
+ *   strio.readlines(sep_string=$/)  =>   array
+ *
+ * See IO#readlines.
+ */
 static VALUE
 strio_readlines(argc, argv, self)
     int argc;
@@ -785,6 +990,16 @@ strio_readlines(argc, argv, self)
     return ary;
 }
 
+/*
+ * call-seq:
+ *   strio.write(string)    => integer
+ *   strio.syswrite(string) => integer
+ *
+ * Appends the given string to the underlying buffer string of *strio*.
+ * The stream must be opened for writing.  If the argument is not a
+ * string, it will be converted to a string using <code>to_s</code>.
+ * Returns the number of bytes written.  See IO#write.
+ */
 static VALUE
 strio_write(self, str)
     VALUE self, str;
@@ -813,12 +1028,37 @@ strio_write(self, str)
     return LONG2NUM(len);
 }
 
+/*
+ * call-seq:
+ *   strio << obj     => strio
+ *
+ * See IO#<<.
+ */
 #define strio_addstr rb_io_addstr
 
+/*
+ * call-seq:
+ *   strio.print()             => nil
+ *   strio.print(obj, ...)     => nil
+ *
+ * See IO#print.
+ */
 #define strio_print rb_io_print
 
+/*
+ * call-seq:
+ *   strio.printf(format_string [, obj, ...] )   => nil
+ *
+ * See IO#printf.
+ */
 #define strio_printf rb_io_printf
 
+/*
+ * call-seq:
+ *   strio.putc(obj)    => obj
+ *
+ * See IO#putc.
+ */
 static VALUE
 strio_putc(self, ch)
     VALUE self, ch;
@@ -838,8 +1078,20 @@ strio_putc(self, ch)
     return ch;
 }
 
+/*
+ * call-seq:
+ *   strio.puts(obj, ...)    => nil
+ *
+ * See IO#puts.
+ */
 #define strio_puts rb_io_puts
 
+/*
+ * call-seq:
+ *   strio.read([length [, buffer]])    => string, buffer, or nil
+ *
+ * See IO#read.
+ */
 static VALUE
 strio_read(argc, argv, self)
     int argc;
@@ -913,6 +1165,13 @@ strio_read(argc, argv, self)
     return str;
 }
 
+/*
+ * call-seq:
+ *   strio.sysread(integer[, outbuf])    => string
+ *
+ * Similar to #read, but raises +EOFError+ at end of string instead of
+ * returning +nil+, as well as IO#sysread does.
+ */
 static VALUE
 strio_sysread(argc, argv, self)
     int argc;
@@ -928,14 +1187,29 @@ strio_sysread(argc, argv, self)
 
 #define strio_syswrite strio_write
 
+/* call-seq: strio.path -> nil */
 #define strio_path strio_nil
 
+/*
+ * call-seq:
+ *   strio.isatty -> nil
+ *   strio.tty? -> nil
+ *
+ */
 #define strio_isatty strio_false
 
+/* call-seq: strio.pid -> nil */
 #define strio_pid strio_nil
 
+/* call-seq: strio.fileno -> nil */
 #define strio_fileno strio_nil
 
+/*
+ * call-seq:
+ *   strio.size   => integer
+ *
+ * Returns the size of the buffer string.
+ */
 static VALUE
 strio_size(self)
     VALUE self;
@@ -947,6 +1221,13 @@ strio_size(self)
     return ULONG2NUM(RSTRING(string)->len);
 }
 
+/*
+ * call-seq:
+ *   strio.truncate(integer)    => 0
+ *
+ * Truncates the buffer string to at most _integer_ bytes. The *strio*
+ * must be opened for writing.
+ */
 static VALUE
 strio_truncate(self, len)
     VALUE self, len;
@@ -964,6 +1245,9 @@ strio_truncate(self, len)
     return len;
 }
 
+/*
+ * Pseudo I/O on String object.
+ */
 void
 Init_stringio()
 {