Add RDoc for Kernel global functions, tidy array and error

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

ChangeLog

@@ -1,8 +1,12 @@
-Mon Dec 29 11:00:16 2003  Dave Thomas  <dave@wireless_3.local.thomases.com>
+Mon Dec 29 12:51:02 2003  Dave Thomas  <dave@pragprog.com>
+
+	* eval.c: Add RDoc for Kernel global functions.
+
+Mon Dec 29 11:00:16 2003  Dave Thomas  <dave@pragprog.com>
 
 	* array.c: Tidy up RDoc loose ends.
 
-Mon Dec 29 05:05:51 2003  Dave Thomas  <dave@wireless_3.local.thomases.com>
+Mon Dec 29 05:05:51 2003  Dave Thomas  <dave@pragprog.com>
 
 	* struct.c, random: Add RDoc comments
 
@@ -10,7 +14,7 @@ Mon Dec 29 02:25:00 2003  Gavin Sinclair <gsinclair@soyabean.com.au>
 
 	* lib/optparse.rb: Improved documentation.
 
-Mon Dec 29 02:20:54 2003  Dave Thomas  <dave@wireless_3.local.thomases.com>
+Mon Dec 29 02:20:54 2003  Dave Thomas  <dave@pragprog.com>
 
 	* eval.c: Add RDoc for class Proc, Method, UnboundMethod
 

bignum.c

@@ -1916,6 +1916,13 @@ rb_big_aref(x, y)
     return INT2FIX(0);
 }
 
+/*
+ * call-seq:
+ *   big.hash   => fixnum
+ *
+ * Compute a hash based on the value of _big_.
+ */
+
 static VALUE
 rb_big_hash(x)
     VALUE x;

enum.c

@@ -728,6 +728,20 @@ max_ii(i, memo)
     return Qnil;
 }
 
+/*
+ *  call-seq:
+ *     enum.max                   => obj
+ *     enum.max {|a,b| block }    => obj
+ *  
+ *  Returns the object in _enum_ with the maximum value. The
+ *  first form assumes all objects implement <code>Comparable</code>;
+ *  the second uses the block to return <em>a <=> b</em>.
+ *     
+ *     a = %w(albatross dog horse)
+ *     a.max                                  #=> "horse"
+ *     a.max {|a,b| a.length <=> b.length }   #=> "albatross"
+ */  
+
 static VALUE
 enum_max(obj)
     VALUE obj;

error.c

@@ -162,6 +162,14 @@ rb_warning(fmt, va_alist)
     va_end(args);
 }
 
+/*
+ * call-seq:
+ *    warn(msg)   => nil
+ *
+ * Display the given message (followed by a newline) on STDERR unless
+ * warnings are disabled (for example with the <code>-W0</code> flag).
+ */
+
 static VALUE
 rb_warn_m(self, mesg)
     VALUE self, mesg;
@@ -517,6 +525,13 @@ exc_set_backtrace(exc, bt)
     return rb_iv_set(exc, "bt", check_backtrace(bt));
 }
 
+/*
+ * call-seq:
+ *   SystemExit.new(status=0)   => system_exit
+ *
+ * Create a new +SystemExit+ exception with the given status.
+ */
+
 static VALUE
 exit_initialize(argc, argv, exc)
     int argc;
@@ -533,6 +548,15 @@ exit_initialize(argc, argv, exc)
     return exc;
 }
 
+
+/*
+ * call-seq:
+ *   system_exit.status   => fixnum
+ *
+ * Return the status value associated with this system exit.
+ */
+
+
 static VALUE
 exit_status(exc)
     VALUE exc;
@@ -564,6 +588,15 @@ rb_name_error(id, fmt, va_alist)
     rb_exc_raise(exc);
 }
 
+/*
+ * call-seq:
+ *   NameError.new(msg [, name])  => name_error
+ *
+ * Construct a new NameError exception. If given the <i>name</i>
+ * parameter may subsequently be examined using the <code>NameError.name</code>
+ * method.
+ */
+
 static VALUE
 name_err_initialize(argc, argv, self)
     int argc;
@@ -578,6 +611,13 @@ name_err_initialize(argc, argv, self)
     return self;
 }
 
+/*
+ *  call-seq:
+ *    name_error.name    =>  string or nil
+ *
+ *  Return the name associated with this NameError exception.
+ */
+
 static VALUE
 name_err_name(self)
     VALUE self;
@@ -585,6 +625,16 @@ name_err_name(self)
     return rb_attr_get(self, rb_intern("name"));
 }
 
+/*
+ * call-seq:
+ *   NoMethodError.new(msg, name [, args])  => no_method_error
+ *
+ * Contruct a NoMethodError exception for a method of the given name
+ * called with the given arguments. The name may be accessed using
+ * the <code>#name</code> method on the resulting object, and the
+ * arguments using the <code>#args</code> method.
+ */
+
 static VALUE
 nometh_err_initialize(argc, argv, self)
     int argc;
@@ -597,6 +647,14 @@ nometh_err_initialize(argc, argv, self)
     return self;
 }
 
+/*
+ * call-seq:
+ *   no_method_error.args  => obj
+ *
+ * Return the arguments passed in as the third parameter to
+ * the constructor.
+ */
+
 static VALUE
 nometh_err_args(self)
     VALUE self;
@@ -679,6 +737,17 @@ get_syserr(n)
     return error;
 }
 
+/*
+ * call-seq:
+ *   SystemCallError.new(msg, errno)  => system_call_error_subclass
+ *
+ * If _errno_ corresponds to a known system error code, constructs
+ * the appropriate <code>Errno</code> class for that error, otherwise
+ * constructs a generic <code>SystemCallError</code> object. The
+ * error number is subsequently available via the <code>errno</code>
+ * method.
+ */
+
 static VALUE
 syserr_initialize(argc, argv, self)
     int argc;
@@ -726,6 +795,13 @@ syserr_initialize(argc, argv, self)
     return self;
 }
 
+/*
+ * call-seq:
+ *   system_call_error.errno   => fixnum
+ *
+ * Return this SystemCallError's error number.
+ */
+
 static VALUE
 syserr_errno(self)
     VALUE self;
@@ -733,6 +809,15 @@ syserr_errno(self)
     return rb_attr_get(self, rb_intern("errno"));
 }
 
+/*
+ * call-seq:
+ *   system_call_error === other  => true or false
+ *
+ * Return +true+ if the receiver is a generic +SystemCallError+, or
+ * if the error numbers _self_ and _other_ are the same.
+ */
+
+
 static VALUE
 syserr_eqq(self, exc)
     VALUE self, exc;

lib/rdoc/parsers/parse_c.rb

@@ -334,7 +334,7 @@ module RDoc
     
     ############################################################
 
-    # Find the C code corresponding to a c method
+    # Find the C code corresponding to a Ruby method
     def find_body(meth_name, meth_obj, body)
       if body =~ %r{((?>/\*.*?\*/\s+))(static\s+)?VALUE\s+#{meth_name}
                     \s*(\(.*?\)).*?^}xm

variable.c

@@ -531,6 +531,29 @@ rb_trace_eval(cmd, val)
     rb_eval_cmd(cmd, rb_ary_new3(1, val), 0);
 }
 
+/*
+ *  call-seq:
+ *     trace_var(symbol, cmd )             => nil
+ *     trace_var(symbol) {|val| block }    => nil
+ *  
+ *  Controls tracing of assignments to global variables. The parameter
+ *  +symbol_ identifies the variable (as either a string name or a
+ *  symbol identifier). _cmd_ (which may be a string or a
+ *  +Proc+ object) or block is executed whenever the variable
+ *  is assigned. The block or +Proc+ object receives the
+ *  variable's new value as a parameter. Also see
+ *  <code>Kernel::untrace_var</code>.
+ *     
+ *     trace_var :$_, proc {|v| puts "$_ is now '#{v}'" }
+ *     $_ = "hello"
+ *     $_ = ' there'
+ *     
+ *  <em>produces:</em>
+ *     
+ *     $_ is now 'hello'
+ *     $_ is now ' there'
+ */
+
 VALUE
 rb_f_trace_var(argc, argv)
     int argc;
@@ -584,6 +607,16 @@ remove_trace(var)
     var->trace = t.next;
 }
 
+/*
+ *  call-seq:
+ *     untrace_var(symbol [, cmd] )   => array or nil
+ *  
+ *  Removes tracing for the specified command on the given global
+ *  variable and returns +nil+. If no command is specified,
+ *  removes all tracing for that variable and returns an array
+ *  containing the commands actually removed.
+ */
+
 VALUE
 rb_f_untrace_var(argc, argv)
     int argc;
@@ -722,6 +755,15 @@ gvar_i(key, entry, ary)
     return ST_CONTINUE;
 }
 
+/*
+ *  call-seq:
+ *     global_variables    => array
+ *  
+ *  Returns an array of the names of global variables.
+ *     
+ *     global_variables.grep /std/   #=> ["$stderr", "$stdout", "$stdin"]
+ */
+
 VALUE
 rb_f_global_variables()
 {