Add RDoc for kernel functions, and tidy up

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

ChangeLog

@@ -1,3 +1,8 @@
+Wed Dec 31 01:33:05 2003  Dave Thomas  <dave@pragprog.com>
+
+	* array.c, error.c, eval.c, io.c, prec.c, range.c, re.c,
+          string.c, time.c: Add RDoc for Kernel functions, and tidy.
+
 Tue Dec 30 12:30:30 2003  Dave Thomas  <dave@pragprog.com>
 
 	* lib/rdoc/code_objects.rb (RDoc::Context::find_symbol): If a

array.c

@@ -1727,7 +1727,7 @@ rb_values_at(obj, olen, argc, argv, func)
  *   Returns an array containing the elements in
  *   _self_ corresponding to the given selector(s). The selectors
  *   may be either integer indices or ranges. 
- *   See also </code>.select<code>.
+ *   See also <code>.select</code>.
  * 
  *      a = %w{ a b c d e f }
  *      a.values_at(1, 3, 5)
@@ -1754,9 +1754,6 @@ rb_ary_values_at(argc, argv, ary)
  *  returns a true value (equivalent to <code>Enumerable#select</code>).
  *     
  *     a = %w{ a b c d e f }
- *     a.select(1, 3, 5)               #=> ["b", "d", "f"]
- *     a.select(1, 3, 5, 7)            #=> ["b", "d", "f", nil]
- *     a.select(-1, -3, -5, -7)        #=> ["f", "d", "b", nil]
  *     a.select {|v| v =~ /[aeiou]/}   #=> ["a", "e"]
  */
 

error.c

@@ -353,6 +353,8 @@ exc_initialize(argc, argv, exc)
 }
 
 /*
+ *  Document-method: exception
+ *
  *  call-seq:
  *     exc.exception(string) -> an_exception or exc
  *  

eval.c

@@ -11367,6 +11367,24 @@ rb_thread_yield(arg, th)
     return rb_yield_0(arg, 0, 0, Qtrue, Qtrue);
 }
 
+/*
+ *  call-seq:
+ *     Thread.new([arg]*) {|args| block }   => thread
+ *  
+ *  Creates and runs a new thread to execute the instructions given in
+ *  <i>block</i>. Any arguments passed to <code>Thread::new</code> are passed
+ *  into the block.
+ *     
+ *     x = Thread.new { sleep 0.1; print "x"; print "y"; print "z" }
+ *     a = Thread.new { print "a"; print "b"; sleep 0.2; print "c" }
+ *     x.join # Let the threads finish before
+ *     a.join # main thread exits...
+ *     
+ *  <em>produces:</em>
+ *     
+ *     abxyzc
+ */
+
 static VALUE
 rb_thread_s_new(argc, argv, klass)
     int argc;
@@ -11900,6 +11918,13 @@ rb_thread_keys(thread)
     return ary;
 }
 
+/*
+ * call-seq:
+ *   thr.inspect   => string
+ *
+ * Dump the name, id, and status of _thr_ to a string.
+ */
+
 static VALUE
 rb_thread_inspect(thread)
     VALUE thread;
@@ -12253,13 +12278,12 @@ thgroup_add(group, thread)
 
 
 /*
- *  <code>Thread</code> encapsulates the behavior of a thread of
+ *  +Thread+ encapsulates the behavior of a thread of
  *  execution, including the main thread of the Ruby script.
  *     
- *  In the descriptions of the methods in this class, the parameter <i>sym</i>
+ *  In the descriptions of the methods in this class, the parameter _sym_
- *  refers to a symbol, which is either a quoted string or a <code>Symbol</code>
+ *  refers to a symbol, which is either a quoted string or a 
- *  (such as <code>:name</code>).
+ *  +Symbol+ (such as <code>:name</code>).
- *     
  */
 
 void

io.c

@@ -2879,6 +2879,88 @@ rb_io_s_sysopen(argc, argv)
     return INT2NUM(fd);
 }
 
+/*
+ *  call-seq:
+ *     open(path [, mode [, perm]] )                => io or nil
+ *     open(path [, mode [. perm]] ) {|io| block }  => nil
+ *  
+ *  Creates an <code>IO</code> object connected to the given stream,
+ *  file, or subprocess.
+ *     
+ *  If <i>path</i> does not start with a pipe character
+ *  (``<code>|</code>''), treat it as the name of a file to open using
+ *  the specified mode (defaulting to ``<code>r</code>''). (See the table
+ *  of valid modes on page 331.) If a file is being created, its initial
+ *  permissions may be set using the integer third parameter.
+ *     
+ *  If a block is specified, it will be invoked with the
+ *  <code>File</code> object as a parameter, and the file will be
+ *  automatically closed when the block terminates. The call always
+ *  returns <code>nil</code> in this case.
+ *     
+ *  If <i>path</i> starts with a pipe character, a subprocess is
+ *  created, connected to the caller by a pair of pipes. The returned
+ *  <code>IO</code> object may be used to write to the standard input
+ *  and read from the standard output of this subprocess. If the command
+ *  following the ``<code>|</code>'' is a single minus sign, Ruby forks,
+ *  and this subprocess is connected to the parent. In the subprocess,
+ *  the <code>open</code> call returns <code>nil</code>. If the command
+ *  is not ``<code>-</code>'', the subprocess runs the command. If a
+ *  block is associated with an <code>open("|-")</code> call, that block
+ *  will be run twice---once in the parent and once in the child. The
+ *  block parameter will be an <code>IO</code> object in the parent and
+ *  <code>nil</code> in the child. The parent's <code>IO</code> object
+ *  will be connected to the child's <code>$stdin</code> and
+ *  <code>$stdout</code>. The subprocess will be terminated at the end
+ *  of the block.
+ *     
+ *     open("testfile") do |f|
+ *       print f.gets
+ *     end
+ *     
+ *  <em>produces:</em>
+ *     
+ *     This is line one
+ *     
+ *  Open a subprocess and read its output:
+ *     
+ *     cmd = open("|date")
+ *     print cmd.gets
+ *     cmd.close
+ *     
+ *  <em>produces:</em>
+ *     
+ *     Wed Apr  9 08:56:31 CDT 2003
+ *     
+ *  Open a subprocess running the same Ruby program:
+ *     
+ *     f = open("|-", "w+")
+ *     if f == nil
+ *       puts "in Child"
+ *       exit
+ *     else
+ *       puts "Got: #{f.gets}"
+ *     end
+ *     
+ *  <em>produces:</em>
+ *     
+ *     Got: in Child
+ *     
+ *  Open a subprocess using a block to receive the I/O object:
+ *     
+ *     open("|-") do |f|
+ *       if f == nil
+ *         puts "in Child"
+ *       else
+ *         puts "Got: #{f.gets}"
+ *       end
+ *     end
+ *     
+ *  <em>produces:</em>
+ *     
+ *     Got: in Child
+ */
+
 static VALUE
 rb_f_open(argc, argv)
     int argc;
@@ -3173,6 +3255,17 @@ rb_io_printf(argc, argv, out)
     return Qnil;
 }
 
+/*
+ *  call-seq:
+ *     printf(io, string [, obj ... ] )    => nil
+ *     printf(string [, obj ... ] )        => nil
+ *  
+ *  Equivalent to:
+ *     io.write(sprintf(string, obj, ...)
+ *  or
+ *     $defout.write(sprintf(string, obj, ...)
+ */
+
 static VALUE
 rb_f_printf(argc, argv)
     int argc;
@@ -3249,6 +3342,29 @@ rb_io_print(argc, argv, out)
     return Qnil;
 }
 
+/*
+ *  call-seq:
+ *     print(obj, ...)    => nil
+ *  
+ *  Prints each object in turn to <code>$defout</code>. If the output
+ *  field separator (<code>$,</code>) is not +nil+, its
+ *  contents will appear between each field. If the output record
+ *  separator (<code>$\</code>) is not +nil+, it will be
+ *  appended to the output. If no arguments are given, prints
+ *  <code>$_</code>. Objects that aren't strings will be converted by
+ *  calling their <code>to_s</code> method.
+ *     
+ *     print "cat", [1,2,3], 99, "\n"
+ *     $, = ", "
+ *     $\ = "\n"
+ *     print "cat", [1,2,3], 99
+ *     
+ *  <em>produces:</em>
+ *     
+ *     cat12399
+ *     cat, 1, 2, 3, 99
+ */
+
 static VALUE
 rb_f_print(argc, argv)
     int argc;
@@ -3284,6 +3400,15 @@ rb_io_putc(io, ch)
     return ch;
 }
 
+/*
+ *  call-seq:
+ *     putc(int)   => int
+ *  
+ *  Equivalent to:
+ *
+ *    $defout.putc(int)
+ */
+
 static VALUE
 rb_f_putc(recv, ch)
     VALUE recv, ch;
@@ -3364,6 +3489,15 @@ rb_io_puts(argc, argv, out)
     return Qnil;
 }
 
+/*
+ *  call-seq:
+ *     puts(obj, ...)    => nil
+ *  
+ *  Equivalent to 
+ *
+ *      $defout.puts(obj, ...)
+ */
+
 static VALUE
 rb_f_puts(argc, argv)
     int argc;
@@ -3381,6 +3515,24 @@ rb_p(obj)			/* for debug print within C code */
     rb_io_write(rb_stdout, rb_default_rs);
 }
 
+/*
+ *  call-seq:
+ *     p(obj, ...)    => nil
+ *  
+ *  For each object, directly writes
+ *  _obj_.+inspect+ followed by the current output
+ *  record separator to the program's standard output. +p+
+ *  bypasses the Ruby I/O libraries.
+ *     
+ *     S = Struct.new(:name, :state)
+ *     s = S['dave', 'TX']
+ *     p s
+ *     
+ *  <em>produces:</em>
+ *     
+ *     #<S name="dave", state="TX">
+ */
+
 static VALUE
 rb_f_p(argc, argv)
     int argc;
@@ -3397,6 +3549,29 @@ rb_f_p(argc, argv)
     return Qnil;
 }
 
+/*
+ *  call-seq:
+ *     obj.display(port=$>)    => nil
+ *  
+ *  Prints <i>obj</i> on the given port (default <code>$></code>).
+ *  Equivalent to:
+ *     
+ *     def display(port=$>)
+ *       port.write self
+ *     end
+ *     
+ *  For example:
+ *     
+ *     1.display
+ *     "cat".display
+ *     [ 4, 5, 6 ].display
+ *     puts
+ *     
+ *  <em>produces:</em>
+ *     
+ *     1cat456
+ */
+
 static VALUE
 rb_obj_display(argc, argv, self)
     int argc;
@@ -3561,6 +3736,28 @@ rb_io_initialize(argc, argv, io)
     return io;
 }
 
+
+/*
+ *  call-seq:
+ *     File.new(filename, mode="r")            => file
+ *     File.new(filename [, mode [, perm]])    => file
+ *  
+
+ *  Opens the file named by _filename_ according to
+ *  _mode_ (default is ``r'') and returns a new
+ *  <code>File</code> object. See the description of class +IO+ for
+ *  a description of _mode_. The file mode may optionally be
+ *  specified as a +Fixnum+ by _or_-ing together the
+ *  flags (O_RDONLY etc, again described under +IO+). Optional
+ *  permission bits may be given in _perm_. These mode and permission
+ *  bits are platform dependent; on Unix systems, see
+ *  <code>open(2)</code> for details.
+ *
+ *     f = File.new("testfile", "r")
+ *     f = File.new("newfile",  "w+")
+ *     f = File.new("newfile", File::CREAT|File::TRUNC|File::RDWR, 0644)
+ */
+
 static VALUE
 rb_file_initialize(argc, argv, io)
     int argc;
@@ -3820,6 +4017,35 @@ argf_getline(argc, argv)
     return line;
 }
 
+/*
+ *  call-seq:
+ *     gets(separator=$/)    => string or nil
+ *  
+ *  Returns (and assigns to <code>$_</code>) the next line from the list
+ *  of files in +ARGV+ (or <code>$*</code>), or from standard
+ *  input if no files are present on the command line. Returns
+ *  +nil+ at end of file. The optional argument specifies the
+ *  record separator. The separator is included with the contents of
+ *  each record. A separator of +nil+ reads the entire
+ *  contents, and a zero-length separator reads the input one paragraph
+ *  at a time, where paragraphs are divided by two consecutive newlines.
+ *  If multiple filenames are present in +ARGV+,
+ *  +gets(nil)+ will read the contents one file at a time.
+ *     
+ *     ARGV << "testfile"
+ *     print while gets
+ *     
+ *  <em>produces:</em>
+ *     
+ *     This is line one
+ *     This is line two
+ *     This is line three
+ *     And so on...
+ *     
+ *  The style of programming using <code>$_</code> as an implicit
+ *  parameter is gradually losing favor in the Ruby community.
+ */
+
 static VALUE
 rb_f_gets(argc, argv)
     int argc;
@@ -3864,6 +4090,14 @@ rb_gets()
     return line;
 }
 
+/*
+ *  call-seq:
+ *     readline(separator=$/    => string
+ *  
+ *  Equivalent to <code>Kernel::gets</code>, except
+ *  +readline+ raises +EOFError+ at end of file.
+ */
+
 static VALUE
 rb_f_readline(argc, argv)
     int argc;
@@ -3880,6 +4114,9 @@ rb_f_readline(argc, argv)
     return line;
 }
 
+/*
+ * obsolete
+ */
 static VALUE
 rb_f_getc()
 {
@@ -3890,6 +4127,14 @@ rb_f_getc()
     return rb_io_getc(rb_stdin);
 }
 
+/*
+ *  call-seq:
+ *     readlines(separator=$/)    => array
+ *  
+ *  Returns an array containing the lines returned by calling
+ *  <code>Kernel.gets(<i>aString</i>)</code> until the end of file.
+ */
+
 static VALUE
 rb_f_readlines(argc, argv)
     int argc;
@@ -3906,6 +4151,20 @@ rb_f_readlines(argc, argv)
     return ary;
 }
 
+/*
+ *  call-seq:
+ *     `cmd`    => string
+ *  
+ *  Returns the standard output of running _cmd_ in a subshell.
+ *  The built-in syntax <code>%x{...}</code> uses
+ *  this method. Sets <code>$?</code> to the process status.
+ *     
+ *     `date`                   #=> "Wed Apr  9 08:56:30 CDT 2003\n"
+ *     `ls testdir`.split[1]    #=> "main.rb"
+ *     `echo oops && exit 99`   #=> "oops\n"
+ *     $?.exitstatus            #=> 99
+ */
+
 static VALUE
 rb_f_backquote(obj, str)
     VALUE obj, str;
@@ -4230,6 +4489,25 @@ rb_io_fcntl(argc, argv, io)
 #endif
 }
 
+/*
+ *  call-seq:
+ *     syscall(fixnum [, args...])   => integer
+ *  
+ *  Calls the operating system function identified by _fixnum_,
+ *  passing in the arguments, which must be either +String+
+ *  objects, or +Integer+ objects that ultimately fit within
+ *  a native +long+. Up to nine parameters may be passed (14
+ *  on the Atari-ST). The function identified by _fixnum_ is system
+ *  dependent. On some Unix systems, the numbers may be obtained from a
+ *  header file called <code>syscall.h</code>.
+ *     
+ *     syscall 4, 1, "hello\n", 6   # '4' is write(2) on our box
+ *     
+ *  <em>produces:</em>
+ *     
+ *     hello
+ */
+
 static VALUE
 rb_f_syscall(argc, argv)
     int argc;

lib/rdoc/parsers/parse_c.rb

@@ -264,7 +264,10 @@ module RDoc
         next if meth_name == "initialize_copy"
 
         # Ignore top-object and weird struct.c dynamic stuff
-        next if var_name  == "ruby_top_self" || var_name == "nstr"
+        next if var_name == "ruby_top_self" 
+        next if var_name == "nstr"
+        next if var_name == "envtbl"
+        next if var_name == "argf"   # it'd be nice to handle this one
                           
         var_name = "rb_cObject" if var_name == "rb_mKernel"
         handle_method(type, var_name, meth_name, 
@@ -358,18 +361,7 @@ module RDoc
         override_comment = find_override_comment(meth_obj.name)
         comment = override_comment if override_comment
 
-        # 
+        find_call_seq(comment, meth_obj) if comment
-        # If the comment block contains a section that looks like
-        #    call-seq:
-        #        Array.new
-        #        Array.new(10)
-        # use it for the parameters
-
-        if comment.sub!(/call-seq:(.*?)^\s*\*?\s*$/m, '')
-          seq = $1
-          seq.gsub!(/^\s*\*\s*/, '')
-          meth_obj.call_seq = seq
-        end
         
 #        meth_obj.params = params
         meth_obj.start_collecting_tokens
@@ -377,7 +369,32 @@ module RDoc
         meth_obj.comment = mangle_comment(comment)
         
       else
-        $stderr.puts "No definition for #{meth_name}"
+
+        # No body, but might still have an override comment
+        comment = find_override_comment(meth_obj.name)
+
+        if comment
+          find_call_seq(comment, meth_obj)
+          meth_obj.comment = mangle_comment(comment)
+        else
+          $stderr.puts "No definition for #{meth_name}"
+        end
+      end
+    end
+
+
+    ##################################################
+    # 
+    # If the comment block contains a section that looks like
+    #    call-seq:
+    #        Array.new
+    #        Array.new(10)
+    # use it for the parameters
+    def find_call_seq(comment, meth_obj)
+      if comment.sub!(/call-seq:(.*?)^\s*\*?\s*$/m, '')
+        seq = $1
+        seq.gsub!(/^\s*\*\s*/, '')
+        meth_obj.call_seq = seq
       end
     end
 

prec.c

@@ -16,6 +16,21 @@ VALUE rb_mPrecision;
 
 static ID prc_pr, prc_if;
 
+
+/*
+ *  call-seq:
+ *   num.prec(klass)   => a_klass
+ *
+ *  Converts _self_ into an instance of _klass_. By default,
+ *  +prec+ invokes 
+ *
+ *     klass.induced_from(num)
+ *
+ *  and returns its value. So, if <code>klass.induced_from</code>
+ *  doesn't return an instance of _klass_, it will be necessary
+ *  to reimplement +prec+.
+ */
+
 static VALUE
 prec_prec(x, klass)
     VALUE x, klass;
@@ -23,6 +38,14 @@ prec_prec(x, klass)
     return rb_funcall(klass, prc_if, 1, x);
 }
 
+/*
+ *  call-seq:
+ *    num.prec_i  =>  Integer
+ *
+ *  Returns an +Integer+ converted from _num_. It is equivalent 
+ *  to <code>prec(Integer)</code>.
+ */
+
 static VALUE
 prec_prec_i(x)
     VALUE x;
@@ -32,6 +55,14 @@ prec_prec_i(x)
     return rb_funcall(x, prc_pr, 1, klass);
 }
 
+/*
+ *  call-seq:
+ *    num.prec_f  =>  Integer
+ *
+ *  Returns an +Float+ converted from _num_. It is equivalent 
+ *  to <code>prec(Float)</code>.
+ */
+
 static VALUE
 prec_prec_f(x)
     VALUE x;
@@ -41,6 +72,19 @@ prec_prec_f(x)
     return rb_funcall(x, prc_pr, 1, klass);
 }
 
+/*
+ * call-seq:
+ *   Mod.induced_from(number)  =>  a_mod
+ * 
+ * Creates an instance of mod from. This method is overridden
+ * by concrete +Numeric+ classes, so that (for example)
+ *
+ *   Fixnum.induced_from(9.9)   #=>  9
+ *
+ * Note that a use of +prec+ in a redefinition may cause
+ * an infinite loop.
+ */
+
 static VALUE
 prec_induced_from(module, x)
     VALUE module, x;
@@ -50,6 +94,15 @@ prec_induced_from(module, x)
     return Qnil;		/* not reached */
 }
 
+/*
+ * call_seq:
+ *   included
+ *
+ * When the +Precision+ module is mixed-in to a class, this +included+
+ * method is used to add our default +induced_from+ implementation
+ * to the host class.
+ */
+
 static VALUE
 prec_included(module, include)
     VALUE module, include;
@@ -66,6 +119,13 @@ prec_included(module, include)
     return module;
 }
 
+/*
+ * Precision is a mixin for concrete numeric classes with
+ * precision.  Here, `precision' means the fineness of approximation
+ * of a real number, so, this module should not be included into
+ * anything which is not a ubset of Real (so it should not be
+ * included in classes such as +Complex+ or +Matrix+).
+*/
 
 void
 Init_Precision()

range.c

@@ -195,6 +195,15 @@ range_eql(range, obj)
     return Qtrue;
 }
 
+/*
+ * call-seq:
+ *   rng.hash    => fixnum
+ *
+ * Generate a hash value such that two ranges with the same start and
+ * end points, and the same value for the "exclude end" flag, generate
+ * the same hash value.
+ */
+
 static VALUE
 range_hash(range)
     VALUE range;
@@ -361,7 +370,9 @@ each_i(v, arg)
  *     rng.each {| i | block } => rng
  *  
  *  Iterates over the elements <i>rng</i>, passing each in turn to the
- *  block.
+ *  block. You can only iterate if the start object of the range
+ *  supports the +succ+ method (which means that you can't iterate over
+ *  ranges of +Float+ objects).
  *     
  *     (10..15).each do |n|
  *        print n, ' '
@@ -484,6 +495,13 @@ rb_range_beg_len(range, begp, lenp, len, err)
     return Qnil;
 }
 
+/*
+ * call-seq:
+ *   rng.to_s   => string
+ *
+ * Convert this range object to a printable form.
+ */
+
 static VALUE
 range_to_s(range)
     VALUE range;
@@ -500,6 +518,16 @@ range_to_s(range)
     return str;
 }
 
+/*
+ * call-seq:
+ *   rng.inspect  => string
+ *
+ * Convert this range object to a printable form (using 
+ * <code>inspect</code> to convert the start and end
+ * objects).
+ */
+
+
 static VALUE
 range_inspect(range)
     VALUE range;
@@ -526,6 +554,14 @@ member_i(v, args)
     }
 }
 
+/*
+ * call-seq:
+ *   rng.member?(val)   =>  true or false
+ *
+ * Return +true+ if _val_ is one of the values in _rng_ (that is if
+ * <code>Range#each</code> would return _val_ at some point).
+ */
+
 static VALUE
 range_member(range, val)
     VALUE range, val;

re.c

@@ -386,6 +386,17 @@ rb_reg_source(re)
     return str;
 }
 
+/*
+ * call-seq:
+ *    rxp.inspect   => string
+ *
+ * Produce a nicely formatted string-version of _rxp_. Perhaps surprisingly,
+ * <code>#inspect</code> actually produces the more natural version of
+ * the string than <code>#to_s</code>.
+ *
+ *     /ab+c/ix.to_s         #=> /ab+c/ix
+*/
+
 static VALUE
 rb_reg_inspect(re)
     VALUE re;
@@ -1416,6 +1427,13 @@ rb_reg_cur_kcode(re)
     return 0;
 }
 
+/*
+ * call-seq:
+ *   rxp.hash   => fixnum
+ *
+ * Produce a hash based on the text and options of this regular expression.
+ */
+
 static VALUE
 rb_reg_hash(re)
     VALUE re;
@@ -1591,6 +1609,13 @@ rb_reg_match_m(re, str)
     return result;
 }
 
+/*
+ * Document-method: compile
+ *
+ * Synonym for <code>Regexp.new</code>
+ */
+
+
 /*
  *  call-seq:
  *     Regexp.new(string [, options [, lang]])       => regexp
@@ -2267,6 +2292,6 @@ Init_Regexp()
     rb_define_method(rb_cMatch, "pre_match", rb_reg_match_pre, 0);
     rb_define_method(rb_cMatch, "post_match", rb_reg_match_post, 0);
     rb_define_method(rb_cMatch, "to_s", match_to_s, 0);
-    rb_define_method(rb_cMatch, "inspect", rb_any_to_s, 0);
+    rb_define_method(rb_cMatch, "inspect", rb_any_to_s, 0); // in object.c
     rb_define_method(rb_cMatch, "string", match_string, 0);
 }

string.c

@@ -837,6 +837,13 @@ rb_str_hash(str)
     return key;
 }
 
+/*
+ * call-seq:
+ *    str.hash   => fixnum
+ *
+ * Return a hash based on the string's length and content.
+ */
+
 static VALUE
 rb_str_hash_m(str)
     VALUE str;
@@ -893,6 +900,13 @@ rb_str_equal(str1, str2)
     return Qfalse;
 }
 
+/*
+ * call-seq:
+ *   str.eql?(other)   => true or false
+ *
+ * Two strings are equal if the have the same length and content.
+ */
+
 static VALUE
 rb_str_eql(str1, str2)
     VALUE str1, str2;
@@ -2223,6 +2237,14 @@ uscore_get()
     return line;
 }
 
+/*
+ *  call-seq:
+ *     sub!(pattern, replacement)    => $_ or nil
+ *     sub!(pattern) {|...| block }  => $_ or nil
+ *  
+ *  Equivalent to <code>$_.sub!(<i>args</i>)</code>.
+ */
+
 static VALUE
 rb_f_sub_bang(argc, argv)
     int argc;
@@ -2231,6 +2253,15 @@ rb_f_sub_bang(argc, argv)
     return rb_str_sub_bang(argc, argv, uscore_get());
 }
 
+/*
+ *  call-seq:
+ *     sub(pattern, replacement)   => $_
+ *     sub(pattern) { block }      => $_
+ *  
+ *  Equivalent to <code>$_.sub(<i>args</i>)</code>, except that
+ *  <code>$_</code> will be updated if substitution occurs.
+ */
+
 static VALUE
 rb_f_sub(argc, argv)
     int argc;
@@ -2244,6 +2275,19 @@ rb_f_sub(argc, argv)
     return str;
 }
 
+/*
+ *  call-seq:
+ *     gsub!(pattern, replacement)    => string or nil
+ *     gsub!(pattern) {|...| block }  => string or nil
+ *  
+ *  Equivalent to <code>Kernel::gsub</code>, except <code>nil</code> is
+ *  returned if <code>$_</code> is not modified.
+ *     
+ *     $_ = "quick brown fox"
+ *     gsub! /cat/, '*'   #=> nil
+ *     $_                 #=> "quick brown fox"
+ */
+
 static VALUE
 rb_f_gsub_bang(argc, argv)
     int argc;
@@ -2252,6 +2296,19 @@ rb_f_gsub_bang(argc, argv)
     return rb_str_gsub_bang(argc, argv, uscore_get());
 }
 
+/*
+ *  call-seq:
+ *     gsub(pattern, replacement)    => string
+ *     gsub(pattern) {|...| block }  => string
+ *  
+ *  Equivalent to <code>$_.gsub...</code>, except that <code>$_</code>
+ *  receives the modified result.
+ *     
+ *     $_ = "quick brown fox"
+ *     gsub /[aeiou]/, '*'   #=> "q**ck br*wn f*x"
+ *     $_                    #=> "q**ck br*wn f*x"
+ */
+
 static VALUE
 rb_f_gsub(argc, argv)
     int argc;
@@ -2448,6 +2505,18 @@ rb_str_to_s(str)
     return str;
 }
 
+/*
+ * call-seq:
+ *   str.inspect   => string
+ *
+ * Returns a printable version of _str_, with special characters
+ * escaped.
+ *
+ *    str = "hello"
+ *    str[3] = 8
+ *    str.inspect       #=> "hel\010o"
+ */
+
 VALUE
 rb_str_inspect(str)
     VALUE str;
@@ -3494,6 +3563,14 @@ rb_str_split(str, sep0)
     return rb_str_split_m(1, &sep, str);
 }
 
+/*
+ *  call-seq:
+ *     split([pattern [, limit]])    => array
+ *  
+ *  Equivalent to <code>$_.split(<i>pattern</i>, <i>limit</i>)</code>.
+ *  See <code>String#split</code>.
+ */
+
 static VALUE
 rb_f_split(argc, argv)
     int argc;
@@ -3678,11 +3755,19 @@ rb_str_chop(str)
 
 /*
  *  call-seq:
- *     str.chop!   => str or nil
+ *     chop!    => $_ or nil
  *  
- *  Processes <i>str</i> as for <code>String#chop</code>, returning <i>str</i>,
+ *  Equivalent to <code>$_.chop!</code>.
- *  or <code>nil</code> if <i>str</i> is the empty string.  See also
+ *     
- *  <code>String#chomp!</code>.
+ *     a  = "now\r\n"
+ *     $_ = a
+ *     chop!   #=> "now"
+ *     chop!   #=> "no"
+ *     chop!   #=> "n"
+ *     chop!   #=> ""
+ *     chop!   #=> nil
+ *     $_      #=> ""
+ *     a       #=> ""
  */
 
 static VALUE
@@ -3692,6 +3777,24 @@ rb_f_chop_bang(str)
     return rb_str_chop_bang(uscore_get());
 }
 
+/*
+ *  call-seq:
+ *     chop   => string
+ *  
+ *  Equivalent to <code>($_.dup).chop!</code>, except <code>nil</code>
+ *  is never returned. See <code>String#chop!</code>.
+ *     
+ *     a  =  "now\r\n"
+ *     $_ = a
+ *     chop   #=> "now"
+ *     $_     #=> "now"
+ *     chop   #=> "no"
+ *     chop   #=> "n"
+ *     chop   #=> ""
+ *     chop   #=> ""
+ *     a      #=> "now\r\n"
+ */
+
 static VALUE
 rb_f_chop()
 {
@@ -3815,6 +3918,21 @@ rb_str_chomp(argc, argv, str)
     return str;
 }
 
+/*
+ *  call-seq:
+ *     chomp!             => $_ or nil
+ *     chomp!(string)     => $_ or nil
+ *  
+ *  Equivalent to <code>$_.chomp!(<em>string</em>)</code>. See
+ *  <code>String#chomp!</code>
+ *     
+ *     $_ = "now\n"
+ *     chomp!       #=> "now"
+ *     $_           #=> "now"
+ *     chomp! "x"   #=> nil
+ *     $_           #=> "now"
+ */
+
 static VALUE
 rb_f_chomp_bang(argc, argv)
     int argc;
@@ -3823,6 +3941,23 @@ rb_f_chomp_bang(argc, argv)
     return rb_str_chomp_bang(argc, argv, uscore_get());
 }
 
+/*
+ *  call-seq:
+ *     chomp            => $_
+ *     chomp(string)    => $_
+ *  
+ *  Equivalent to <code>$_ = $_.chomp(<em>string</em>)</code>. See
+ *  <code>String#chomp</code>.
+ *     
+ *     $_ = "now\n"
+ *     chomp         #=> "now"
+ *     $_            #=> "now"
+ *     chomp "ow"    #=> "n"
+ *     $_            #=> "n"
+ *     chomp "xxx"   #=> "n"
+ *     $_            #=> "n"
+ */
+
 static VALUE
 rb_f_chomp(argc, argv)
     int argc;
@@ -4091,6 +4226,15 @@ rb_str_scan(str, pat)
     return str;
 }
 
+/*
+ *  call-seq:
+ *     scan(pattern)                   => array
+ *     scan(pattern) {|///| block }    => $_
+ *  
+ *  Equivalent to calling <code>$_.scan</code>. See
+ *  <code>String#scan</code>.
+ */
+
 static VALUE
 rb_f_scan(self, pat)
     VALUE self, pat;

time.c

@@ -66,6 +66,13 @@ time_modify(time)
 	rb_raise(rb_eSecurityError, "Insecure: can't modify Time");
 }
 
+/*
+ *  Document-method: now
+ *
+ *  Synonym for <code>Time.new</code>. Returns a +Time+ object
+ *  initialized tot he current system time.
+ */
+
 /*
  *  call-seq:
  *     Time.new -> time
@@ -1780,6 +1787,10 @@ time_s_times(obj)
     return rb_proc_times(obj);
 }
 
+/*
+ * undocumented
+ */
+
 static VALUE
 time_mdump(time)
     VALUE time;
@@ -1820,6 +1831,13 @@ time_mdump(time)
     return rb_str_new(buf, 8);
 }
 
+/*
+ * call-seq:
+ *   time._dump   => string
+ *
+ * Dump _time_ for marshaling.
+ */
+
 static VALUE
 time_dump(argc, argv, time)
     int argc;
@@ -1838,6 +1856,10 @@ time_dump(argc, argv, time)
     return str;
 }
 
+/*
+ * undocumented
+ */
+
 static VALUE
 time_mload(time, str)
     VALUE time, str;
@@ -1890,6 +1912,13 @@ time_mload(time, str)
     return time;
 }
 
+/*
+ * call-seq:
+ *   Time._load(string)   => time
+ *
+ * Unmarshal a dumped +Time+ object.
+ */
+
 static VALUE
 time_load(klass, str)
     VALUE klass, str;