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/