[前][次][番号順一覧][スレッド一覧]

ruby-changes:29937

From: zzak <ko1@a...>
Date: Tue, 16 Jul 2013 03:27:35 +0900 (JST)
Subject: [ruby-changes:29937] zzak:r41989 (trunk): * numeric.c: [DOC] improve rdoc formatting for parameters and links

zzak	2013-07-16 03:27:23 +0900 (Tue, 16 Jul 2013)

  New Revision: 41989

  http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=41989

  Log:
    * numeric.c: [DOC] improve rdoc formatting for parameters and links

  Modified files:
    trunk/ChangeLog
    trunk/numeric.c

Index: ChangeLog
===================================================================
--- ChangeLog	(revision 41988)
+++ ChangeLog	(revision 41989)
@@ -1,3 +1,7 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1
+Tue Jul 16 03:23:03 2013  Zachary Scott  <e@z...>
+
+	* numeric.c: [DOC] improve rdoc formatting for parameters and links
+
 Mon Jul 15 14:40:00 2013  Tanaka Akira  <akr@f...>
 
 	* include/ruby/intern.h (rb_big2str0): Deprecated.
Index: numeric.c
===================================================================
--- numeric.c	(revision 41988)
+++ numeric.c	(revision 41989)
@@ -198,12 +198,13 @@ rb_num_negative_p(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L198
  *  call-seq:
  *     num.coerce(numeric)  ->  array
  *
- *  If <i>aNumeric</i> is the same type as <i>num</i>, returns an array
- *  containing <i>aNumeric</i> and <i>num</i>. Otherwise, returns an
- *  array with both <i>aNumeric</i> and <i>num</i> represented as
- *  <code>Float</code> objects. This coercion mechanism is used by
- *  Ruby to handle mixed-type numeric operations: it is intended to
- *  find a compatible common type between the two operands of the operator.
+ *  If a +numeric is the same type as +num+, returns an array containing
+ *  +numeric+ and +num+. Otherwise, returns an array with both a +numeric+ and
+ *  +num+ represented as Float objects.
+ *
+ *  This coercion mechanism is used by Ruby to handle mixed-type numeric
+ *  operations: it is intended to find a compatible common type between the two
+ *  operands of the operator.
  *
  *     1.coerce(2.5)   #=> [2.5, 1.0]
  *     1.2.coerce(3)   #=> [3.0, 1.2]
@@ -297,8 +298,9 @@ rb_num_coerce_relop(VALUE x, VALUE y, ID https://github.com/ruby/ruby/blob/trunk/numeric.c#L298
 }
 
 /*
- * Trap attempts to add methods to <code>Numeric</code> objects. Always
- * raises a <code>TypeError</code>
+ * Trap attempts to add methods to Numeric objects. Always raises a TypeError.
+ *
+ * Numerics should be values; singleton_methods should not be added to them.
  */
 
 static VALUE
@@ -306,7 +308,6 @@ num_sadded(VALUE x, VALUE name) https://github.com/ruby/ruby/blob/trunk/numeric.c#L308
 {
     ID mid = rb_to_id(name);
     /* ruby_frame = ruby_frame->prev; */ /* pop frame for "singleton_method_added" */
-    /* Numerics should be values; singleton_methods should not be added to them */
     rb_remove_method_id(rb_singleton_class(x), mid);
     rb_raise(rb_eTypeError,
 	     "can't define singleton method \"%s\" for %s",
@@ -316,11 +317,14 @@ num_sadded(VALUE x, VALUE name) https://github.com/ruby/ruby/blob/trunk/numeric.c#L317
     UNREACHABLE;
 }
 
-/* :nodoc: */
+/*
+ * Numerics are immutable values, which should not be copied.
+ *
+ * Any attempt to use this method on a Numeric will raise a TypeError.
+ */
 static VALUE
 num_init_copy(VALUE x, VALUE y)
 {
-    /* Numerics are immutable values, which should not be copied */
     rb_raise(rb_eTypeError, "can't copy %s", rb_obj_classname(x));
 
     UNREACHABLE;
@@ -390,14 +394,12 @@ num_fdiv(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L394
  *  call-seq:
  *     num.div(numeric)  ->  integer
  *
- *  Uses <code>/</code> to perform division, then converts the result to
- *  an integer. <code>numeric</code> does not define the <code>/</code>
- *  operator; this is left to subclasses.
+ *  Uses +/+ to perform division, then converts the result to an integer.
+ *  +numeric+ does not define the +/+ operator; this is left to subclasses.
  *
- *  Equivalent to
- *  <i>num</i>.<code>divmod(</code><i>aNumeric</i><code>)[0]</code>.
+ *  Equivalent to <code>num.divmod(numeric)[0]</code>.
  *
- *  See <code>Numeric#divmod</code>.
+ *  See Numeric#divmod.
  */
 
 static VALUE
@@ -414,10 +416,9 @@ num_div(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L416
  *
  *     x.modulo(y) means x-y*(x/y).floor
  *
- *  Equivalent to
- *  <i>num</i>.<code>divmod(</code><i>aNumeric</i><code>)[1]</code>.
+ *  Equivalent to <code>num.divmod(numeric)[1]</code>.
  *
- *  See <code>Numeric#divmod</code>.
+ *  See Numeric#divmod.
  */
 
 static VALUE
@@ -434,7 +435,7 @@ num_modulo(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L435
  *
  *     x.remainder(y) means x-y*(x/y).truncate
  *
- *  See <code>Numeric#divmod</code>.
+ *  See Numeric#divmod.
  */
 
 static VALUE
@@ -456,9 +457,10 @@ num_remainder(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L457
  *  call-seq:
  *     num.divmod(numeric)  ->  array
  *
- *  Returns an array containing the quotient and modulus obtained by
- *  dividing <i>num</i> by <i>numeric</i>. If <code>q, r =
- *  x.divmod(y)</code>, then
+ *  Returns an array containing the quotient and modulus obtained by dividing
+ *  +num+ by +numeric+.
+ *
+ *  If <code>q, r = * x.divmod(y)</code>, then
  *
  *      q = floor(x/y)
  *      x = q*y+r
@@ -503,8 +505,7 @@ num_divmod(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L505
  *  call-seq:
  *     num.real?  ->  true or false
  *
- *  Returns <code>true</code> if <i>num</i> is a <code>Real</code>
- *  (i.e. non <code>Complex</code>).
+ *  Returns +true+ if +num+ is a Real number. (i.e. not Complex).
  */
 
 static VALUE
@@ -534,11 +535,13 @@ num_int_p(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L535
  *     num.abs        ->  numeric
  *     num.magnitude  ->  numeric
  *
- *  Returns the absolute value of <i>num</i>.
+ *  Returns the absolute value of +num+.
  *
  *     12.abs         #=> 12
  *     (-34.56).abs   #=> 34.56
  *     -34.56.abs     #=> 34.56
+ *
+ *  Numeric#magnitude is an alias of Numeric#abs.
  */
 
 static VALUE
@@ -555,7 +558,7 @@ num_abs(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L558
  *  call-seq:
  *     num.zero?  ->  true or false
  *
- *  Returns <code>true</code> if <i>num</i> has a zero value.
+ *  Returns +true+ if +num+ has a zero value.
  */
 
 static VALUE
@@ -572,8 +575,9 @@ num_zero_p(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L575
  *  call-seq:
  *     num.nonzero?  ->  self or nil
  *
- *  Returns +self+ if <i>num</i> is not zero, <code>nil</code>
- *  otherwise. This behavior is useful when chaining comparisons:
+ *  Returns +self+ if +num+ is not zero, +nil+ otherwise.
+ *
+ *  This behavior is useful when chaining comparisons:
  *
  *     a = %w( z Bb bB bb BB a aA Aa AA A )
  *     b = a.sort {|a,b| (a.downcase <=> b.downcase).nonzero? || a <=> b }
@@ -611,9 +615,8 @@ num_to_int(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L615
  *
  * Document-class: Float
  *
- *  <code>Float</code> objects represent inexact real numbers using
- *  the native architecture's double-precision floating point
- *  representation.
+ *  Float objects represent inexact real numbers using the native
+ *  architecture's double-precision floating point representation.
  *
  *  Floating point has a different arithmetic and is a inexact number.
  *  So you should know its esoteric system. see following:
@@ -635,12 +638,11 @@ rb_float_new_in_heap(double d) https://github.com/ruby/ruby/blob/trunk/numeric.c#L638
 
 /*
  *  call-seq:
- *     flt.to_s  ->  string
+ *     float.to_s  ->  string
  *
- *  Returns a string containing a representation of self. As well as a
- *  fixed or exponential form of the number, the call may return
- *  ``<code>NaN</code>'', ``<code>Infinity</code>'', and
- *  ``<code>-Infinity</code>''.
+ *  Returns a string containing a representation of self. As well as a fixed or
+ *  exponential form of the +float+, the call may return +NaN+, +Infinity+, and
+ *  +-Infinity+.
  */
 
 static VALUE
@@ -714,11 +716,12 @@ flo_to_s(VALUE flt) https://github.com/ruby/ruby/blob/trunk/numeric.c#L716
 
 /*
  *  call-seq:
- *     flt.coerce(numeric)  ->  array
+ *     float.coerce(numeric)  ->  array
  *
- *  Returns an array with both <i>aNumeric</i> and <i>flt</i> represented
- *  as <code>Float</code> objects.
- *  This is achieved by converting <i>aNumeric</i> to a <code>Float</code>.
+ *  Returns an array with both a +numeric+ and a +float+ represented as Float
+ *  objects.
+ *
+ *  This is achieved by converting a +numeric+ to a Float.
  *
  *     1.2.coerce(3)       #=> [3.0, 1.2]
  *     2.5.coerce(1.1)     #=> [1.1, 2.5]
@@ -747,8 +750,7 @@ flo_uminus(VALUE flt) https://github.com/ruby/ruby/blob/trunk/numeric.c#L750
  * call-seq:
  *   float + other  ->  float
  *
- * Returns a new float which is the sum of <code>float</code>
- * and <code>other</code>.
+ * Returns a new float which is the sum of +float+ and +other+.
  */
 
 static VALUE
@@ -770,8 +772,7 @@ flo_plus(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L772
  * call-seq:
  *   float - other  ->  float
  *
- * Returns a new float which is the difference of <code>float</code>
- * and <code>other</code>.
+ * Returns a new float which is the difference of +float+ and +other+.
  */
 
 static VALUE
@@ -793,8 +794,7 @@ flo_minus(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L794
  * call-seq:
  *   float * other  ->  float
  *
- * Returns a new float which is the product of <code>float</code>
- * and <code>other</code>.
+ * Returns a new float which is the product of +float+ and +other+.
  */
 
 static VALUE
@@ -816,8 +816,7 @@ flo_mul(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L816
  * call-seq:
  *   float / other  ->  float
  *
- * Returns a new float which is the result of dividing
- * <code>float</code> by <code>other</code>.
+ * Returns a new float which is the result of dividing +float+ by +other+.
  */
 
 static VALUE
@@ -845,7 +844,7 @@ flo_div(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L844
  *     float.fdiv(numeric)  ->  float
  *     float.quo(numeric)  ->  float
  *
- *  Returns float / numeric.
+ *  Returns <code>float / numeric</code>, same as Float#/.
  */
 
 static VALUE
@@ -978,9 +977,9 @@ flo_divmod(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L977
 /*
  * call-seq:
  *
- *  flt ** other  ->  float
+ *  float ** other  ->  float
  *
- * Raises <code>float</code> the <code>other</code> power.
+ * Raises +float+ to the power of +other+.
  *
  *    2.0**3      #=> 8.0
  */
@@ -1010,8 +1009,8 @@ flo_pow(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1009
  *  call-seq:
  *     num.eql?(numeric)  ->  true or false
  *
- *  Returns <code>true</code> if <i>num</i> and <i>numeric</i> are the
- *  same type and have equal values.
+ *  Returns +true+ if +num+ and +numeric+ are the same type and have equal
+ *  values.
  *
  *     1 == 1.0          #=> true
  *     1.eql?(1.0)       #=> false
@@ -1050,11 +1049,11 @@ num_equal(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1049
 
 /*
  *  call-seq:
- *     flt == obj  ->  true or false
+ *     float == obj  ->  true or false
+ *
+ *  Returns +true+ only if +obj+ has the same value as +float+. Contrast this
+ *  with Float#eql?, which requires obj to be a Float.
  *
- *  Returns <code>true</code> only if <i>obj</i> has the same value
- *  as <i>flt</i>. Contrast this with <code>Float#eql?</code>, which
- *  requires <i>obj</i> to be a <code>Float</code>.
  *  The result of <code>NaN == NaN</code> is undefined, so the
  *  implementation-dependent value is returned.
  *
@@ -1089,7 +1088,7 @@ flo_eq(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1088
 
 /*
  * call-seq:
- *   flt.hash  ->  integer
+ *   float.hash  ->  integer
  *
  * Returns a hash code for this float.
  */
@@ -1169,9 +1168,10 @@ flo_cmp(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1168
 
 /*
  * call-seq:
- *   flt > real  ->  true or false
+ *   float > real  ->  true or false
+ *
+ * Returns +true+ if +float+ is greater than +real+.
  *
- * <code>true</code> if <code>flt</code> is greater than <code>real</code>.
  * The result of <code>NaN > NaN</code> is undefined, so the
  * implementation-dependent value is returned.
  */
@@ -1210,10 +1210,10 @@ flo_gt(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1210
 
 /*
  * call-seq:
- *   flt >= real  ->  true or false
+ *   float >= real  ->  true or false
+ *
+ * Returns +true+ if +float+ is greater than or equal to +real+.
  *
- * <code>true</code> if <code>flt</code> is greater than
- * or equal to <code>real</code>.
  * The result of <code>NaN >= NaN</code> is undefined, so the
  * implementation-dependent value is returned.
  */
@@ -1252,9 +1252,10 @@ flo_ge(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1252
 
 /*
  * call-seq:
- *   flt < real  ->  true or false
+ *   float < real  ->  true or false
+ *
+ * Returns +true+ if +float+ is less than +real+.
  *
- * <code>true</code> if <code>flt</code> is less than <code>real</code>.
  * The result of <code>NaN < NaN</code> is undefined, so the
  * implementation-dependent value is returned.
  */
@@ -1293,10 +1294,10 @@ flo_lt(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1294
 
 /*
  * call-seq:
- *   flt <= real  ->  true or false
+ *   float <= real  ->  true or false
+ *
+ * Returns +true+ if +float+ is less than or equal to +real+.
  *
- * <code>true</code> if <code>flt</code> is less than
- * or equal to <code>real</code>.
  * The result of <code>NaN <= NaN</code> is undefined, so the
  * implementation-dependent value is returned.
  */
@@ -1335,11 +1336,11 @@ flo_le(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1336
 
 /*
  *  call-seq:
- *     flt.eql?(obj)  ->  true or false
+ *     float.eql?(obj)  ->  true or false
+ *
+ *  Returns +true+ only if +obj+ is a Float with the same value as +float+.
+ *  Contrast this with Float#==, which performs type conversions.
  *
- *  Returns <code>true</code> only if <i>obj</i> is a
- *  <code>Float</code> with the same value as <i>flt</i>. Contrast this
- *  with <code>Float#==</code>, which performs type conversions.
  *  The result of <code>NaN.eql?(NaN)</code> is undefined, so the
  *  implementation-dependent value is returned.
  *
@@ -1363,9 +1364,9 @@ flo_eql(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1364
 
 /*
  * call-seq:
- *   flt.to_f  ->  self
+ *   float.to_f  ->  self
  *
- * As <code>flt</code> is already a float, returns +self+.
+ * Since +float+ is already a float, returns +self+.
  */
 
 static VALUE
@@ -1376,10 +1377,10 @@ flo_to_f(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1377
 
 /*
  *  call-seq:
- *     flt.abs        ->  float
- *     flt.magnitude  ->  float
+ *     float.abs        ->  float
+ *     float.magnitude  ->  float
  *
- *  Returns the absolute value of <i>flt</i>.
+ *  Returns the absolute value of +float+.
  *
  *     (-34.56).abs   #=> 34.56
  *     -34.56.abs     #=> 34.56
@@ -1395,9 +1396,9 @@ flo_abs(VALUE flt) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1396
 
 /*
  *  call-seq:
- *     flt.zero?  ->  true or false
+ *     float.zero?  ->  true or false
  *
- *  Returns <code>true</code> if <i>flt</i> is 0.0.
+ *  Returns +true+ if +float+ is 0.0.
  *
  */
 
@@ -1412,10 +1413,9 @@ flo_zero_p(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1413
 
 /*
  *  call-seq:
- *     flt.nan?  ->  true or false
+ *     float.nan?  ->  true or false
  *
- *  Returns <code>true</code> if <i>flt</i> is an invalid IEEE floating
- *  point number.
+ *  Returns +true+ if +float+ is an invalid IEEE floating point number.
  *
  *     a = -1.0      #=> -1.0
  *     a.nan?        #=> false
@@ -1433,10 +1433,15 @@ flo_is_nan_p(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1433
 
 /*
  *  call-seq:
- *     flt.infinite?  ->  nil, -1, +1
+ *     float.infinite?  ->  nil, -1, +1
+ *
+ *  Return values corresponding to the value of +float+:
+ *
+ *  +finite+::	    +nil+
+ *  +-Infinity+::   +-1+
+ *  ++Infinity+::   +1+
  *
- *  Returns <code>nil</code>, -1, or +1 depending on whether <i>flt</i>
- *  is finite, -infinity, or +infinity.
+ *  For example:
  *
  *     (0.0).infinite?        #=> nil
  *     (-1.0/0.0).infinite?   #=> -1
@@ -1457,11 +1462,10 @@ flo_is_infinite_p(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1462
 
 /*
  *  call-seq:
- *     flt.finite?  ->  true or false
+ *     float.finite?  ->  true or false
  *
- *  Returns <code>true</code> if <i>flt</i> is a valid IEEE floating
- *  point number (it is not infinite, and <code>nan?</code> is
- *  <code>false</code>).
+ *  Returns +true+ if +float+ is a valid IEEE floating point number (it is not
+ *  infinite, and Float#nan? is +false+).
  *
  */
 
@@ -1483,9 +1487,9 @@ flo_is_finite_p(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1487
 
 /*
  *  call-seq:
- *     flt.floor  ->  integer
+ *     float.floor  ->  integer
  *
- *  Returns the largest integer less than or equal to <i>flt</i>.
+ *  Returns the largest integer less than or equal to +float+.
  *
  *     1.2.floor      #=> 1
  *     2.0.floor      #=> 2
@@ -1508,10 +1512,9 @@ flo_floor(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1512
 
 /*
  *  call-seq:
- *     flt.ceil  ->  integer
+ *     float.ceil  ->  integer
  *
- *  Returns the smallest <code>Integer</code> greater than or equal to
- *  <i>flt</i>.
+ *  Returns the smallest Integer greater than or equal to +float+.
  *
  *     1.2.ceil      #=> 2
  *     2.0.ceil      #=> 2
@@ -1576,10 +1579,11 @@ flo_truncate(VALUE num); https://github.com/ruby/ruby/blob/trunk/numeric.c#L1579
 
 /*
  *  call-seq:
- *     flt.round([ndigits])  ->  integer or float
+ *     float.round([ndigits])  ->  integer or float
  *
- *  Rounds <i>flt</i> to a given precision in decimal digits (default 0 digits).
- *  Precision may be negative.  Returns a floating point number when ndigits
+ *  Rounds +float+ to a given precision in decimal digits (default 0 digits).
+ *
+ *  Precision may be negative.  Returns a floating point number when +ndigits+
  *  is more than zero.
  *
  *     1.4.round      #=> 1
@@ -1655,11 +1659,13 @@ flo_round(int argc, VALUE *argv, VALUE n https://github.com/ruby/ruby/blob/trunk/numeric.c#L1659
 
 /*
  *  call-seq:
- *     flt.to_i      ->  integer
- *     flt.to_int    ->  integer
- *     flt.truncate  ->  integer
+ *     float.to_i      ->  integer
+ *     float.to_int    ->  integer
+ *     float.truncate  ->  integer
+ *
+ *  Returns the +float+ truncated to an Integer.
  *
- *  Returns <i>flt</i> truncated to an <code>Integer</code>.
+ *  Synonyms are #to_i, #to_int, and #truncate.
  */
 
 static VALUE
@@ -1682,9 +1688,10 @@ flo_truncate(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1688
  *  call-seq:
  *     num.floor  ->  integer
  *
- *  Returns the largest integer less than or equal to <i>num</i>.
- *  <code>Numeric</code> implements this by converting <i>anInteger</i>
- *  to a <code>Float</code> and invoking <code>Float#floor</code>.
+ *  Returns the largest integer less than or equal to +num+.
+ *
+ *  Numeric implements this by converting an Integer to a Float and invoking
+ *  Float#floor.
  *
  *     1.floor      #=> 1
  *     (-1).floor   #=> -1
@@ -1701,10 +1708,11 @@ num_floor(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1708
  *  call-seq:
  *     num.ceil  ->  integer
  *
- *  Returns the smallest <code>Integer</code> greater than or equal to
- *  <i>num</i>. Class <code>Numeric</code> achieves this by converting
- *  itself to a <code>Float</code> then invoking
- *  <code>Float#ceil</code>.
+ *  Returns the smallest possible Integer that is greater than or equal to
+ *  +num+.
+ *
+ *  Numeric achieves this by converting itself to a Float then invoking
+ *  Float#ceil.
  *
  *     1.ceil        #=> 1
  *     1.2.ceil      #=> 2
@@ -1722,10 +1730,13 @@ num_ceil(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1730
  *  call-seq:
  *     num.round (... truncated)

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/

[前][次][番号順一覧][スレッド一覧]