* io.c: Add rdoc for ARGF.

  contributed by Run Paint Run Run. [ruby-core:23854]

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

2 files changed, 648 insertions, 6 deletions

diff --git a/ChangeLog b/ChangeLog
index 0397601a24..a3911cb8b8 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+Sun Sep  6 05:19:09 2009  NARUSE, Yui  <naruse@ruby-lang.org>
+
+	* io.c: Add rdoc for ARGF.
+	  contributed by Run Paint Run Run. [ruby-core:23854]
+
 Sat Sep  5 15:21:13 2009  Nobuyoshi Nakada  <nobu@ruby-lang.org>
 
 	* compile.c (iseq_compile_each): op_asgn to aref should return rhs.
diff --git a/io.c b/io.c
index b7e278083c..eaaf7e6f97 100644
--- a/io.c
+++ b/io.c
@@ -1300,7 +1300,7 @@ rb_io_set_sync(VALUE io, VALUE sync)
  *  operating system actually writes it to disk.
  *
  *  <code>NotImplementedError</code> is raised
- *  if the underlying operating system does not support <em>fsync(2)</em>. 
+ *  if the underlying operating system does not support <em>fsync(2)</em>.
  */
 
 static VALUE
@@ -1329,7 +1329,7 @@ rb_io_fsync(VALUE io)
  *  Immediately writes all buffered data in <em>ios</em> to disk.
  *
  *  <code>NotImplementedError</code> is raised
- *  if the underlying operating system does not support <em>fdatasync(2)</em>. 
+ *  if the underlying operating system does not support <em>fdatasync(2)</em>.
  */
 
 static VALUE
@@ -2275,7 +2275,7 @@ rb_io_getline_fast(rb_io_t *fptr, rb_encoding *enc)
     ENC_CODERANGE_SET(str, cr);
     fptr->lineno++;
     ARGF.last_lineno = fptr->lineno;
-    
+
     return str;
 }
 
@@ -4441,7 +4441,7 @@ static VALUE
 sysopen_func(void *ptr)
 {
     const struct sysopen_struct *data = ptr;
-    const char *fname = RSTRING_PTR(data->fname); 
+    const char *fname = RSTRING_PTR(data->fname);
 #ifdef _WIN32
     if (data->wchar)
 	return (VALUE)rb_w32_wopen((WCHAR *)fname, data->oflags, data->perm);
@@ -6541,6 +6541,24 @@ argf_initialize_copy(VALUE argf, VALUE orig)
     return argf;
 }
 
+/*
+ *  call-seq:
+ *     ARGF.lineno = number  => nil
+ *
+ *  Sets the line number of the current file in +ARGF+ to the given +Integer+.
+ *
+ *  +ARGF+ sets the line number automatically as you read data, so normally
+ *  you will not need to set it explicitly. To access the current line number
+ *  use +ARGF.lineno+.
+ *
+ *  For example:
+ *
+ *      ARGF.lineno      #=> 0
+ *      ARGF.readline    #=> "This is line 1\n"
+ *      ARGF.lineno      #=> 1
+ *      ARGF.lineno = 0  #=> nil
+ *      ARGF.lineno      #=> 0
+ */
 static VALUE
 argf_set_lineno(VALUE argf, VALUE val)
 {
@@ -6549,6 +6567,19 @@ argf_set_lineno(VALUE argf, VALUE val)
     return Qnil;
 }
 
+/*
+ *  call-seq:
+ *     ARGF.lineno => Integer
+ *
+ *  Returns the current line number of the current file in +ARGF+. This value
+ *  can be set manually with +ARGF.lineno=+.
+ *
+ *  For example:
+ *
+ *      ARGF.lineno   #=> 0
+ *      ARGF.readline #=> "This is line 1\n"
+ *      ARGF.lineno   #=> 1
+ */
 static VALUE
 argf_lineno(VALUE argf)
 {
@@ -6684,7 +6715,7 @@ argf_next_argv(VALUE argf)
 		}
 		ARGF.current_file = prep_io(fr, FMODE_READABLE, rb_cFile, fn);
 	    }
-	    if (ARGF.binmode) rb_io_ascii8bit_binmode(ARGF.current_file);
+           if (ARGF.binmode) rb_io_ascii8bit_binmode(ARGF.current_file);
 	    if (ARGF.encs.enc) {
 		rb_io_t *fptr;
 
@@ -6798,6 +6829,21 @@ rb_f_gets(int argc, VALUE *argv, VALUE recv)
     return rb_funcall2(argf, rb_intern("gets"), argc, argv);
 }
 
+/*
+ *  call-seq:
+ *     ARGF.gets(sep=$/)     => String
+ *     ARGF.gets(limit)      => String
+ *     ARGF.gets(sep, limit) => String
+ *
+ *  Returns the next line from the current file in +ARGF+.
+ *
+ *  By default lines are assumed to be separated by +$/+; to use a different
+ *  character as a separator, supply it as a +String+ for the _sep_ argument.
+ *
+ *  The optional  _limit_ argument specifies how many characters of each line
+ *  to return. By default all characters are returned.
+ *
+ */
 static VALUE
 argf_gets(int argc, VALUE *argv, VALUE argf)
 {
@@ -6856,6 +6902,23 @@ rb_f_readline(int argc, VALUE *argv, VALUE recv)
     return rb_funcall2(argf, rb_intern("readline"), argc, argv);
 }
 
+
+/*
+ *  call-seq:
+ *     ARGF.readline(sep=$/)     => String
+ *     ARGF.readline(limit)      => String
+ *     ARGF.readline(sep, limit) => String
+ *
+ *  Returns the next line from the current file in +ARGF+.
+ *
+ *  By default lines are assumed to be separated by +$/+; to use a different
+ *  character as a separator, supply it as a +String+ for the _sep_ argument.
+ *
+ *  The optional  _limit_ argument specifies how many characters of each line
+ *  to return. By default all characters are returned.
+ *
+ *  An +EOFError+ is raised at the end of the file.
+ */
 static VALUE
 argf_readline(int argc, VALUE *argv, VALUE argf)
 {
@@ -6892,6 +6955,22 @@ rb_f_readlines(int argc, VALUE *argv, VALUE recv)
     return rb_funcall2(argf, rb_intern("readlines"), argc, argv);
 }
 
+/*
+ *  call-seq:
+ *     ARGF.readlines(sep=$/)     => Array
+ *     ARGF.readlines(limit)      => Array
+ *     ARGF.readlines(sep, limit) => Array
+ *
+ *     ARGF.to_a(sep=$/)     => Array
+ *     ARGF.to_a(limit)      => Array
+ *     ARGF.to_a(sep, limit) => Array
+ *
+ *  Reads +ARGF+'s current file in its entirety, returning an +Array+ of its
+ *  lines, one line per element. Lines are assumed to be separated by _sep_.
+ *
+ *     lines = ARGF.readlines
+ *     lines[0]                #=> "This is line one\n"
+ */
 static VALUE
 argf_readlines(int argc, VALUE *argv, VALUE argf)
 {
@@ -8426,6 +8505,22 @@ rb_stdio_set_default_encoding(void)
     rb_io_set_encoding(1, &val, rb_stderr);
 }
 
+/*
+ *  call-seq:
+ *     ARGF.external_encoding   => encoding
+ *
+ *  Returns the external encoding for files read from +ARGF+ as an +Encoding+
+ *  object. The external encoding is the encoding of the text as stored in a
+ *  file. Contrast with +ARGF.internal_encoding+, which is the encoding used
+ *  to represent this text within Ruby.
+ *
+ *  To set the external encoding use +ARGF.set_encoding+.
+ *
+ * For example:
+ *
+ *     ARGF.external_encoding  #=>  #<Encoding:UTF-8>
+ *
+ */
 static VALUE
 argf_external_encoding(VALUE argf)
 {
@@ -8435,6 +8530,19 @@ argf_external_encoding(VALUE argf)
     return rb_io_external_encoding(rb_io_check_io(ARGF.current_file));
 }
 
+/*
+ *  call-seq:
+ *     ARGF.internal_encoding   => encoding
+ *
+ *  Returns the internal encoding for strings read from +ARGF+ as an
+ *  +Encoding+ object.
+ *
+ *  If +ARGF.set_encoding+ has been called with two encoding names, the second
+ *  is returned. Otherwise, if +Encoding.default_external+ has been set, that
+ *  value is returned. Failing that, if a default external encoding was
+ *  specified on the command-line, that value is used. If the encoding is
+ *  unknown, nil is returned.
+ */
 static VALUE
 argf_internal_encoding(VALUE argf)
 {
@@ -8444,6 +8552,37 @@ argf_internal_encoding(VALUE argf)
     return rb_io_internal_encoding(rb_io_check_io(ARGF.current_file));
 }
 
+/*
+ *  call-seq:
+ *     ARGF.set_encoding(ext_enc)                => ARGF
+ *     ARGF.set_encoding("ext_enc:int_enc")      => ARGF
+ *     ARGF.set_encoding(ext_enc, int_enc)       => ARGF
+ *     ARGF.set_encoding("ext_enc:int_enc", opt) => ARGF
+ *     ARGF.set_encoding(ext_enc, int_enc, opt)  => ARGF
+ *
+ *  If single argument is specified, strings read from ARGF are tagged with
+ *  the encoding specified.
+ *
+ *  If two encoding names separated by a colon are given, e.g. "ascii:utf-8",
+ *  the read string is converted from the first encoding (external encoding)
+ *  to the second encoding (internal encoding), then tagged with the second
+ *  encoding.
+ *
+ *  If two arguments are specified, they must be encoding objects or encoding
+ *  names. Again, the first specifies the external encoding; the second
+ *  specifies the internal encoding.
+ *
+ *  If the external encoding and the internal encoding are specified, the
+ *  optional +Hash+ argument can be used to adjust the conversion process. The
+ *  structure of this hash is explained in the +String#encode+ documentation.
+ *
+ *  For example:
+ *
+ *      ARGF.set_encoding('ascii')         # Tag the input as US-ASCII text
+ *      ARGF.set_encoding(Encoding::UTF_8) # Tag the input as UTF-8 text
+ *      ARGF.set_encoding('utf-8','ascii') # Transcode the input from US-ASCII
+ *                                         # to UTF-8.
+ */
 static VALUE
 argf_set_encoding(int argc, VALUE *argv, VALUE argf)
 {
@@ -8458,6 +8597,18 @@ argf_set_encoding(int argc, VALUE *argv, VALUE argf)
     return argf;
 }
 
+/*
+ *  call-seq:
+ *     ARGF.tell  => Integer
+ *     ARGF.pos   => Integer
+ *
+ *  Returns the current offset (in bytes) of the current file in +ARGF+.
+ *
+ *     ARGF.pos    #=> 0
+ *     ARGF.gets   #=> "This is line one\n"
+ *     ARGF.pos    #=> 17
+ *
+ */
 static VALUE
 argf_tell(VALUE argf)
 {
@@ -8468,6 +8619,13 @@ argf_tell(VALUE argf)
     return rb_io_tell(ARGF.current_file);
 }
 
+/*
+ *  call-seq:
+ *     ARGF.seek(amount, whence=SEEK_SET) -> 0
+ *
+ *  Seeks to offset _amount_ (an +Integer+) in the +ARGF+ stream according to
+ *  the value of _whence_. See +IO#seek+ for further details.
+ */
 static VALUE
 argf_seek_m(int argc, VALUE *argv, VALUE argf)
 {
@@ -8478,6 +8636,17 @@ argf_seek_m(int argc, VALUE *argv, VALUE argf)
     return rb_io_seek_m(argc, argv, ARGF.current_file);
 }
 
+/*
+ *  call-seq:
+ *     ARGF.pos = position  => Integer
+ *
+ *  Seeks to the position given by _position_ (in bytes) in +ARGF+.
+ *
+ *  For example:
+ *
+ *      ARGF.pos = 17
+ *      ARGF.gets   #=> "This is line two\n"
+ */
 static VALUE
 argf_set_pos(VALUE argf, VALUE offset)
 {
@@ -8488,6 +8657,18 @@ argf_set_pos(VALUE argf, VALUE offset)
     return rb_io_set_pos(ARGF.current_file, offset);
 }
 
+/*
+ *  call-seq:
+ *     ARGF.rewind   => 0
+ *
+ *  Positions the current file to the beginning of input, resetting
+ *  +ARGF.lineno+ to zero.
+ *
+ *     ARGF.readline   #=> "This is line one\n"
+ *     ARGF.rewind     #=> 0
+ *     ARGF.lineno     #=> 0
+ *     ARGF.readline   #=> "This is line one\n"
+ */
 static VALUE
 argf_rewind(VALUE argf)
 {
@@ -8498,6 +8679,16 @@ argf_rewind(VALUE argf)
     return rb_io_rewind(ARGF.current_file);
 }
 
+/*
+ *  call-seq:
+ *     ARGF.fileno    => fixnum
+ *     ARGF.to_i      => fixnum
+ *
+ *  Returns an integer representing the numeric file descriptor for
+ *  the current file. Raises an +ArgumentError+ if there isn't a current file.
+ *
+ *     ARGF.fileno    #=> 3
+ */
 static VALUE
 argf_fileno(VALUE argf)
 {
@@ -8508,6 +8699,18 @@ argf_fileno(VALUE argf)
     return rb_io_fileno(ARGF.current_file);
 }
 
+/*
+ *  call-seq:
+ *     ARGF.to_io     => IO
+ *
+ *  Returns an +IO+ object representing the current file. This will be a
+ *  +File+ object unless the current file is a stream such as STDIN.
+ *
+ *  For example:
+ *
+ *     ARGF.to_io    #=> #<File:glark.txt>
+ *     ARGF.to_io    #=> #<IO:<STDIN>>
+ */
 static VALUE
 argf_to_io(VALUE argf)
 {
@@ -8516,6 +8719,24 @@ argf_to_io(VALUE argf)
     return ARGF.current_file;
 }
 
+/*
+ *  call-seq:
+ *     ARGF.eof?  => true or false
+ *     ARGF.eof   => true or false
+ *
+ *  Returns true if the current file in +ARGF+ is at end of file, i.e. it has
+ *  no data to read. The stream must be opened for reading or an +IOError+
+ *  will be raised.
+ *
+ *     $ echo "eof" | ruby argf.rb
+ *
+ *     ARGF.eof?                 #=> false
+ *     3.times { ARGF.readchar }
+ *     ARGF.eof?                 #=> false
+ *     ARGF.readchar             #=> "\n"
+ *     ARGF.eof?                 #=> true
+ */
+
 static VALUE
 argf_eof(VALUE argf)
 {
@@ -8531,6 +8752,43 @@ argf_eof(VALUE argf)
     return Qfalse;
 }
 
+/*
+ *  call-seq:
+ *     ARGF.read([length [, buffer]])    => string, buffer, or nil
+ *
+ *  Reads _length_ bytes from ARGF. The files named on the command line
+ *  are concatenated and treated as a single file by this method, so when
+ *  called without arguments the contents of this pseudo file are returned in
+ *  their entirety.
+ *
+ *  _length_ must be a non-negative integer or nil. If it is a positive
+ *  integer, +read+ tries to read at most _length_ bytes. It returns nil
+ *  if an EOF was encountered before anything could be read. Fewer than
+ *  _length_ bytes may be returned if an EOF is encountered during the read.
+ *
+ *  If _length_ is omitted or is _nil_, it reads until EOF. A String is
+ *  returned even if EOF is encountered before any data is read.
+ *
+ *  If _length_ is zero, it returns _""_.
+ *
+ *  If the optional _buffer_ argument is present, it must reference a String,
+ *  which will receive the data.
+ *
+ * For example:
+ *
+ *     $ echo "small" > small.txt
+ *     $ echo "large" > large.txt
+ *     $ ./glark.rb small.txt large.txt
+ *
+ *     ARGF.read      #=> "small\nlarge"
+ *     ARGF.read(200) #=> "small\nlarge"
+ *     ARGF.read(2)   #=> "sm"
+ *     ARGF.read(0)   #=> ""
+ *
+ *  Note that this method behaves like fread() function in C.  If you need the
+ *  behavior like read(2) system call, consider +ARGF.readpartial+.
+ */
+
 static VALUE
 argf_read(int argc, VALUE *argv, VALUE argf)
 {
@@ -8590,6 +8848,34 @@ argf_forward_call(VALUE arg)
     return Qnil;
 }
 
+/*
+ *  call-seq:
+ *     ARGF.readpartial(maxlen)              => string
+ *     ARGF.readpartial(maxlen, outbuf)      => outbuf
+ *
+ *  Reads at most _maxlen_ bytes from the ARGF stream. It blocks only if
+ *  +ARGF+ has no data immediately available. If the optional _outbuf_
+ *  argument is present, it must reference a String, which will receive the
+ *  data. It raises <code>EOFError</code> on end of file.
+ *
+ *  +readpartial+ is designed for streams such as pipes, sockets, and ttys. It
+ *  blocks only when no data is immediately available. This means that it
+ *  blocks only when following all conditions hold:
+ *
+ *  * The buffer in the +IO+ object is empty.
+ *  * The content of the stream is empty.
+ *  * The stream has not reached EOF.
+ *
+ *  When +readpartial+ blocks, it waits for data or EOF. If some data is read,
+ *  +readpartial+ returns with the data. If EOF is reached, readpartial raises
+ *  an +EOFError+.
+ *
+ *  When +readpartial+ doesn't block, it returns or raises immediately.  If
+ *  the buffer is not empty, it returns the data in the buffer. Otherwise, if
+ *  the stream has some content, it returns the data in the stream. If the
+ *  stream reaches EOF an +EOFError+ is raised.
+ */
+
 static VALUE
 argf_readpartial(int argc, VALUE *argv, VALUE argf)
 {
@@ -8631,6 +8917,29 @@ argf_readpartial(int argc, VALUE *argv, VALUE argf)
     return tmp;
 }
 
+/*
+ *  call-seq:
+ *     ARGF.getc  => String or nil
+ *
+ *  Reads the next character from +ARGF+ and returns it as a +String+. Returns
+ *  +nil+ at the end of the stream.
+ *
+ *  +ARGF+ treats the files named on the command line as a single file created
+ *  by concatenating their contents. After returning the last character of the
+ *  first file, it returns the first character of the second file, and so on.
+ *
+ *  For example:
+ *
+ *     $ echo "foo" > file
+ *     $ ruby argf.rb file
+ *
+ *     ARGF.getc  #=> "f"
+ *     ARGF.getc  #=> "o"
+ *     ARGF.getc  #=> "o"
+ *     ARGF.getc  #=> "\n"
+ *     ARGF.getc  #=> nil
+ *     ARGF.getc  #=> nil
+ */
 static VALUE
 argf_getc(VALUE argf)
 {
@@ -8653,6 +8962,24 @@ argf_getc(VALUE argf)
     return ch;
 }
 
+/*
+ *  call-seq:
+ *     ARGF.getbyte  => Fixnum or nil
+ *
+ *  Gets the next 8-bit byte (0..255) from +ARGF+. Returns +nil+ if called at
+ *  the end of the stream.
+ *
+ *  For example:
+ *
+ *     $ echo "foo" > file
+ *     $ ruby argf.rb file
+ *
+ *     ARGF.getbyte #=> 102
+ *     ARGF.getbyte #=> 111
+ *     ARGF.getbyte #=> 10
+ *     ARGF.getbyte #=> nil
+ *     ARGF.getbyte #=> nil
+ */
 static VALUE
 argf_getbyte(VALUE argf)
 {
@@ -8675,6 +9002,24 @@ argf_getbyte(VALUE argf)
     return ch;
 }
 
+/*
+ *  call-seq:
+ *     ARGF.readchar  => String or nil
+ *
+ *  Reads the next character from +ARGF+ and returns it as a +String+. Raises
+ *  an +EOFError+ after the last character of the last file has been read.
+ *
+ *  For example:
+ *
+ *     $ echo "foo" > file
+ *     $ ruby argf.rb file
+ *
+ *     ARGF.readchar  #=> "f"
+ *     ARGF.readchar  #=> "o"
+ *     ARGF.readchar  #=> "o"
+ *     ARGF.readchar  #=> "\n"
+ *     ARGF.readchar  #=> end of file reached (EOFError)
+ */
 static VALUE
 argf_readchar(VALUE argf)
 {
@@ -8697,6 +9042,24 @@ argf_readchar(VALUE argf)
     return ch;
 }
 
+/*
+ *  call-seq:
+ *     ARGF.readbyte  => Fixnum
+ *
+ *  Reads the next 8-bit byte from ARGF and returns it as a +Fixnum+. Raises
+ *  an +EOFError+ after the last byte of the last file has been read.
+ *
+ *  For example:
+ *
+ *     $ echo "foo" > file
+ *     $ ruby argf.rb file
+ *
+ *     ARGF.readbyte  #=> 102
+ *     ARGF.readbyte  #=> 111
+ *     ARGF.readbyte  #=> 111
+ *     ARGF.readbyte  #=> 10
+ *     ARGF.readbyte  #=> end of file reached (EOFError)
+ */
 static VALUE
 argf_readbyte(VALUE argf)
 {
@@ -8710,6 +9073,43 @@ argf_readbyte(VALUE argf)
     return c;
 }
 
+/*
+ *  call-seq:
+ *     ARGF.lines(sep=$/)                      => Enumerator
+ *     ARGF.lines(sep=$/)          {|line| }   => Enumerator
+ *     ARGF.lines(sep=$/,limit)                => Enumerator
+ *     ARGF.lines(sep=$/,limit)    {|line| }   => Enumerator
+ *
+ *     ARGF.each_line(sep=$/)                  => Enumerator
+ *     ARGF.each_line(sep=$/)       {|line| }  => Enumerator
+ *     ARGF.each_line(sep=$/,limit)            => Enumerator
+ *     ARGF.each_line(sep=$/,limit) {|line| }  => Enumerator
+ *     ARGF.each(sep=$/)                       => Enumerator
+ *     ARGF.each(sep=$/)            {|line| }  => Enumerator
+ *     ARGF.each(sep=$/,limit)                 => Enumerator
+ *     ARGF.each(sep=$/,limit)      {|line| }  => Enumerator
+ *
+ *  Returns an enumerator which iterates over each line (separated by _sep_,
+ *  which defaults to your platform's newline character) of each file in
+ *  +ARGV+. If a block is supplied, each line in turn will be yielded to the
+ *  block. The optional _limit_ argument is a +Fixnum+ specifying the maximumn
+ *  length of each line; longer lines will be split according to this limit.
+ *
+ *  This method allows you to treat the files supplied on the command line as
+ *  a single file consisting of the concatenation of each named file. After
+ *  the last line of the first file has been returned, the first line of the
+ *  second file is returned. The +ARGF.filename+ and +ARGF.lineno+ methods can
+ *  be used to determine the filename and line number, respectively, of the
+ *  current line.
+ *
+ *  For example, the following code prints out each line of each named file
+ *  prefixed with its line number, displaying the filename once per file:
+ *
+ *     ARGF.lines do |line|
+ *       puts ARGF.filename if ARGF.lineno == 1
+ *       puts "#{ARGF.lineno}: #{line}"
+ *     end
+ */
 static VALUE
 argf_each_line(int argc, VALUE *argv, VALUE argf)
 {
@@ -8721,6 +9121,29 @@ argf_each_line(int argc, VALUE *argv, VALUE argf)
     }
 }
 
+/*
+ *  call-seq:
+ *     ARGF.bytes                => Enumerator
+ *     ARGF.bytes     {|byte| }  => Enumerator
+ *
+ *     ARGF.each_byte            => Enumerator
+ *     ARGF.each_byte {|byte| }  => Enumerator
+ *
+ *  Returns an enumerator which iterates over each byte of each file in
+ *  +ARGV+. If a block is supplied, each byte in turn will be yielded to the
+ *  block. A byte is returned as a +Fixnum+ in the range 0..255.
+ *
+ *  This method allows you to treat the files supplied on the command line as
+ *  a single file consisting of the concatenation of each named file. After
+ *  the last byte of the first file has been returned, the first byte of the
+ *  second file is returned. The +ARGF.filename+ method can be used to
+ *  determine the filename of the current byte.
+ *
+ * For example:
+ *
+ *     ARGF.bytes.to_a  #=> [35, 32, ... 95, 10]
+ *
+ */
 static VALUE
 argf_each_byte(VALUE argf)
 {
@@ -8732,6 +9155,25 @@ argf_each_byte(VALUE argf)
     }
 }
 
+/*
+ *  call-seq:
+ *     ARGF.chars                 => Enumerator
+ *     ARGF.chars      {|char| }  => Enumerator
+ *
+ *     ARGF.each_char             => Enumerator
+ *     ARGF.each_char  {|char| }  => Enumerator
+ *
+ *  Returns an enumerator which iterates over each character of each file in
+ *  +ARGV+. If a block is supplied, each character in turn will be yielded to
+ *  the block.
+ *
+ *  This method allows you to treat the files supplied on the command line as
+ *  a single file consisting of the concatenation of each named file. After
+ *  the last character of the first file has been returned, the first
+ *  character of the second file is returned. The +ARGF.filename+ method can
+ *  be used to determine the name of the file in which the current character
+ *  appears.
+ */
 static VALUE
 argf_each_char(VALUE argf)
 {
@@ -8743,6 +9185,28 @@ argf_each_char(VALUE argf)
     }
 }
 
+/*
+ *  call-seq:
+ *     ARGF.filename  => String
+ *     ARGF.path      => String
+ *
+ *  Returns the current filename. "-" is returned when the current file is
+ *  STDIN.
+ *
+ *  For example:
+ *
+ *     $ echo "foo" > foo
+ *     $ echo "bar" > bar
+ *     $ echo "glark" > glark
+ *
+ *     $ ruby argf.rb foo bar glark
+ *
+ *     ARGF.filename  #=> "foo"
+ *     ARGF.read(5)   #=> "foo\nb"
+ *     ARGF.filename  #=> "bar"
+ *     ARGF.skip
+ *     ARGF.filename  #=> "glark"
+ */
 static VALUE
 argf_filename(VALUE argf)
 {
@@ -8756,6 +9220,24 @@ argf_filename_getter(ID id, VALUE *var)
     return argf_filename(*var);
 }
 
+/*
+ *  call-seq:
+ *     ARGF.file  => IO or File object
+ *
+ *  Returns the current file as an +IO+ or +File+ object. #<IO:<STDIN>> is
+ *  returned when the current file is STDIN.
+ *
+ *  For example:
+ *
+ *     $ echo "foo" > foo
+ *     $ echo "bar" > bar
+ *
+ *     $ ruby argf.rb foo bar
+ *
+ *     ARGF.file      #=> #<File:foo>
+ *     ARGF.read(5)   #=> "foo\nb"
+ *     ARGF.file      #=> #<File:bar>
+ */
 static VALUE
 argf_file(VALUE argf)
 {
@@ -8763,6 +9245,17 @@ argf_file(VALUE argf)
     return ARGF.current_file;
 }
 
+/*
+ *  call-seq:
+ *     ARGF.binmode  => ARGF
+ *
+ *  Puts +ARGF+ into binary mode. Once a stream is in binary mode, it cannot
+ *  be reset to non-binary mode. This option has the following effects:
+ *
+ *  *  Newline conversion is disabled.
+ *  *  Encoding conversion is disabled.
+ *  *  Content is treated as ASCII-8BIT.
+ */
 static VALUE
 argf_binmode_m(VALUE argf)
 {
@@ -8770,16 +9263,42 @@ argf_binmode_m(VALUE argf)
     next_argv();
     ARGF_FORWARD(0, 0);
     rb_io_ascii8bit_binmode(ARGF.current_file);
-
     return argf;
 }
 
+/*
+ *  call-seq:
+ *     ARGF.binmode?  => true or false
+ *
+ *  Returns true if +ARGF+ is being read in binary mode; false otherwise. (To
+ *  enable binary mode use +ARGF.binmode+.
+ *
+ * For example:
+ *
+ *     ARGF.binmode?  #=> false
+ *     ARGF.binmode
+ *     ARGF.binmode?  #=> true
+ */
 static VALUE
 argf_binmode_p(VALUE argf)
 {
     return ARGF.binmode ? Qtrue : Qfalse;
 }
 
+/*
+ *  call-seq:
+ *     ARGF.skip  => ARGF
+ *
+ *  Sets the current file to the next file in ARGV. If there aren't any more
+ *  files it has no effect.
+ *
+ * For example:
+ *
+ *     $ ruby argf.rb foo bar
+ *     ARGF.filename  #=> "foo"
+ *     ARGF.skip
+ *     ARGF.filename  #=> "bar"
+ */
 static VALUE
 argf_skip(VALUE argf)
 {
@@ -8790,6 +9309,24 @@ argf_skip(VALUE argf)
     return argf;
 }
 
+/*
+ *  call-seq:
+ *     ARGF.close  => ARGF
+ *
+ *  Closes the current file and skips to the next in the stream. Trying to
+ *  close a file that has already been closed causes an +IOError+ to be
+ *  raised.
+ *
+ * For example:
+ *
+ *     $ ruby argf.rb foo bar
+ *
+ *     ARGF.filename  #=> "foo"
+ *     ARGF.close
+ *     ARGF.filename  #=> "bar"
+ *     ARGF.close
+ *     ARGF.close     #=> closed stream (IOError)
+ */
 static VALUE
 argf_close_m(VALUE argf)
 {
@@ -8802,6 +9339,13 @@ argf_close_m(VALUE argf)
     return argf;
 }
 
+/*
+ *  call-seq:
+ *     ARGF.closed?  => true or false
+ *
+ *  Returns _true_ if the current file has been closed; _false_ otherwise. Use
+ *  +ARGF.close+ to actually close the current file.
+ */
 static VALUE
 argf_closed(VALUE argf)
 {
@@ -8810,12 +9354,26 @@ argf_closed(VALUE argf)
     return rb_io_closed(ARGF.current_file);
 }
 
+/*
+ *  call-seq:
+ *     ARGF.to_s  => String
+ *
+ *  Returns "ARGF".
+ */
 static VALUE
 argf_to_s(VALUE argf)
 {
     return rb_str_new2("ARGF");
 }
 
+/*
+ *  call-seq:
+ *     ARGF.inplace_mode  => String
+ *
+ *  Returns the file extension appended to the names of modified files under
+ *  inplace-edit mode. This value can be set using +ARGF.inplace_mode=+ or
+ *  passing the +-i+ switch to the Ruby binary.
+ */
 static VALUE
 argf_inplace_mode_get(VALUE argf)
 {
@@ -8829,6 +9387,26 @@ opt_i_get(ID id, VALUE *var)
     return argf_inplace_mode_get(*var);
 }
 
+/*
+ *  call-seq:
+ *     ARGF.inplace_mode = ext  => ARGF
+ *
+ *  Sets the filename extension for inplace editing mode to the given String.
+ *  Each file being edited has this value appended to its filename. The
+ *  modifed file is saved under this new name.
+ *
+ *  For example:
+ *
+ *      $ ruby argf.rb file.txt
+ *
+ *      ARGF.inplace_mode = '.bak'
+ *      ARGF.lines do |line|
+ *        print line.sub("foo","bar")
+ *      end
+ *
+ * Each line of _file.txt_ has the first occurence of "foo" replaced with
+ * "bar", then the new line is written out to _file.txt.bak_.
+ */
 static VALUE
 argf_inplace_mode_set(VALUE argf, VALUE val)
 {
@@ -8865,6 +9443,20 @@ ruby_set_inplace_mode(const char *suffix)
     if (suffix) ARGF.inplace = strdup(suffix);
 }
 
+/*
+ *  call-seq:
+ *     ARGF.argv  => Array
+ *
+ *  Returns the +ARGV+ Array, which contains the arguments passed to your
+ *  script, one per element.
+ *
+ *  For example:
+ *
+ *      $ ruby argf.rb -v glark.txt
+ *
+ *      ARGF.argv   #=> ["-v", "glark.txt"]
+ *
+ */
 static VALUE
 argf_argv(VALUE argf)
 {
@@ -8884,6 +9476,47 @@ rb_get_argv(void)
 }
 
 /*
+ * Document-class:  ARGF
+ *
+ * +ARGF+ is a stream designed for use in scripts that process files given as
+ * command-line arguments, or passed in via STDIN.
+ *
+ * The arguments passed to your script are stored in the +ARGV+ Array, one
+ * argument per element. +ARGF+ assumes that any arguments that aren't
+ * filenames have been removed from +ARGV+. For example:
+ *
+ *     $ ruby argf.rb --verbose file1 file2
+ *
+ *     ARGV  #=> ["--verbose", "file1", "file2"]
+ *     option = ARGV.shift #=> "--verbose"
+ *     ARGV  #=> ["file1", "file2"]
+ *
+ * You can now use +ARGF+ to work with a concatenation of each of these named
+ * files. For instance, +ARGF.read+ will return the contents of _file1_
+ * followed by the contents of _file2_.
+ *
+ * After a file in +ARGV+ has been read, +ARGF+ removes it from the Array.
+ * Thus, after all files have been read +ARGV+ will be empty.
+ *
+ * You can manipulate +ARGV+ yourself to control what +ARGF+ operates on. If
+ * you remove a file from +ARGV+, it is ignored by +ARGF+; if you add files to
+ * +ARGV+, they are treated as if they were named on the command line. For
+ * example:
+ *
+ *     ARGV.replace ["file1"]
+ *     ARGF.readlines # Returns the contents of file1 as an Array
+ *     ARGV           #=> []
+ *     ARGV.replace ["file2", "file3"]
+ *     ARGF.read      # Returns the contents of file2 and file3
+ *
+ * If +ARGV+ is empty, +ARGF+ acts as if it contained STDIN, i.e. the data
+ * piped to your script. For example:
+ *
+ *     $ echo "glark" | ruby -e 'p ARGF.read'
+ *     "glark\n"
+ */
+
+/*
  *  Class <code>IO</code> is the basis for all input and output in Ruby.
  *  An I/O stream may be <em>duplexed</em> (that is, bidirectional), and
  *  so may use more than one native operating system stream.
@@ -9152,6 +9785,10 @@ Init_IO(void)
     rb_define_global_const("STDOUT", rb_stdout);
     rb_define_global_const("STDERR", rb_stderr);
 
+    /*
+     * Hack to get rdoc to regard ARGF as a class:
+     * rb_cARGF = rb_define_class("ARGF", rb_cObject);
+     * */
     rb_cARGF = rb_class_new(rb_cObject);
     rb_set_class_path(rb_cARGF, rb_cObject, "ARGF.class");
     rb_define_alloc_func(rb_cARGF, argf_alloc);