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

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()