[DOC] RDoc for numeric.rb (#8216)

Merged-By: peterzhu2118 <peter@peterzhu.ca>

numeric.rb

@@ -1,29 +1,27 @@
 class Numeric
-  #
+
   #  call-seq:
-  #     num.real?  ->  true or false
+  #    real? -> true or false
   #
-  #  Returns +true+ if +num+ is a real number (i.e. not Complex).
+  #  Returns +true+ if +self+ is a real number (i.e. not Complex).
   #
   def real?
     true
   end
 
-  #
   # call-seq:
-  #    num.real  ->  self
+  #   real -> self
   #
-  # Returns self.
+  # Returns +self+.
   #
   def real
     self
   end
 
-  #
   #  call-seq:
-  #     num.integer?  ->  true or false
+  #    integer? -> true or false
   #
-  #  Returns +true+ if +num+ is an Integer.
+  #  Returns +true+ if +self+ is an Integer.
   #
   #    1.0.integer? # => false
   #    1.integer?   # => true
@@ -32,31 +30,27 @@ class Numeric
     false
   end
 
-  #
   #  call-seq:
-  #     num.finite?  ->  true or false
+  #    finite? -> true or false
   #
-  #  Returns +true+ if +num+ is a finite number, otherwise returns +false+.
+  #  Returns +true+ if +self+ is a finite number, +false+ otherwise.
   #
   def finite?
     true
   end
 
-  #
   #  call-seq:
-  #     num.infinite?  ->  -1, 1, or nil
+  #    infinite? -> -1, 1, or nil
   #
-  #  Returns +nil+, -1, or 1 depending on whether the value is
+  #  Returns +nil+, -1, or 1 depending on whether +self+ is
-  #  finite, <code>-Infinity</code>, or <code>+Infinity</code>.
+  #  finite, <tt>-Infinity</tt>, or <tt>+Infinity</tt>.
   #
   def infinite?
     nil
   end
 
-  #
   # call-seq:
-  #    num.imag       ->  0
+  #   imag -> 0
-  #    num.imaginary  ->  0
   #
   # Returns zero.
   #
@@ -66,12 +60,10 @@ class Numeric
 
   alias imag imaginary
 
-  #
   # call-seq:
-  #    num.conj       ->  self
+  #   conj -> self
-  #    num.conjugate  ->  self
   #
-  # Returns self.
+  # Returns +self+.
   #
   def conjugate
     self
@@ -84,7 +76,7 @@ class Integer
   # call-seq:
   #    -int -> integer
   #
-  # Returns +int+, negated.
+  # Returns +self+, negated.
   def -@
     Primitive.attr! :leaf
     Primitive.cexpr! 'rb_int_uminus(self)'
@@ -93,24 +85,26 @@ class Integer
   # call-seq:
   #   ~int -> integer
   #
-  # One's complement: returns a number where each bit is flipped.
+  # One's complement:
+  # returns the value of +self+ with each bit inverted.
   #
-  # Inverts the bits in an Integer. As integers are conceptually of
+  # Because an integer value is conceptually of infinite length,
-  # infinite length, the result acts as if it had an infinite number of
+  # the result acts as if it had an infinite number of
-  # one bits to the left. In hex representations, this is displayed
+  # one bits to the left.
-  # as two periods to the left of the digits.
+  # In hex representations, this is displayed
+  # as two periods to the left of the digits:
   #
   #   sprintf("%X", ~0x1122334455)    # => "..FEEDDCCBBAA"
+  #
   def ~
     Primitive.attr! :leaf
     Primitive.cexpr! 'rb_int_comp(self)'
   end
 
   # call-seq:
-  #    int.abs        ->  integer
+  #   abs -> integer
-  #    int.magnitude  ->  integer
   #
-  # Returns the absolute value of +int+.
+  # Returns the absolute value of +self+.
   #
   #   (-12345).abs # => 12345
   #   -12345.abs   # => 12345
@@ -122,16 +116,15 @@ class Integer
   end
 
   # call-seq:
-  #    int.bit_length  ->  integer
+  #   bit_length -> integer
   #
-  # Returns the number of bits of the value of +int+.
+  # Returns the number of bits of the value of +self+,
-  #
+  # which is the bit position of the highest-order bit
-  # "Number of bits" means the bit position of the highest bit
+  # that is different from the sign bit
-  # which is different from the sign bit
   # (where the least significant bit has bit position 1).
-  # If there is no such bit (zero or minus one), zero is returned.
+  # If there is no such bit (zero or minus one), returns zero.
   #
-  # I.e. this method returns <i>ceil(log2(int < 0 ? -int : int+1))</i>.
+  # This method returns <tt>ceil(log2(self < 0 ? -self : self + 1))</tt>>.
   #
   #   (-2**1000-1).bit_length   # => 1001
   #   (-2**1000).bit_length     # => 1000
@@ -155,31 +148,33 @@ class Integer
   #   (2**1000).bit_length      # => 1001
   #   (2**1000+1).bit_length    # => 1001
   #
-  # This method can be used to detect overflow in Array#pack as follows:
+  # For \Integer _n_,
+  # this method can be used to detect overflow in Array#pack:
   #
   #   if n.bit_length < 32
-  #      [n].pack("l") # no overflow
+  #     [n].pack('l') # No overflow.
   #   else
-  #      raise "overflow"
+  #     raise 'Overflow'
   #   end
+  #
   def bit_length
     Primitive.attr! :leaf
     Primitive.cexpr! 'rb_int_bit_length(self)'
   end
 
   #  call-seq:
-  #     int.even?  ->  true or false
+  #    even? -> true or false
   #
-  #  Returns +true+ if +int+ is an even number.
+  #  Returns +true+ if +self+ is an even number, +false+ otherwise.
   def even?
     Primitive.attr! :leaf
     Primitive.cexpr! 'rb_int_even_p(self)'
   end
 
   #  call-seq:
-  #     int.integer?  ->  true
+  #    integer? -> true
   #
-  #  Since +int+ is already an Integer, this always returns +true+.
+  #  Since +self+ is already an \Integer, always returns +true+.
   def integer?
     true
   end
@@ -187,34 +182,28 @@ class Integer
   alias magnitude abs
 
   #  call-seq:
-  #     int.odd?  ->  true or false
+  #    odd? -> true or false
   #
-  #  Returns +true+ if +int+ is an odd number.
+  #  Returns +true+ if +self+ is an odd number, +false+ otherwise.
   def odd?
     Primitive.attr! :leaf
     Primitive.cexpr! 'rb_int_odd_p(self)'
   end
 
   #  call-seq:
-  #     int.ord  ->  self
+  #    ord -> self
   #
-  #  Returns the +int+ itself.
+  #  Returns +self+;
-  #
+  #  intended for compatibility to character literals in Ruby 1.9.
-  #     97.ord   #=> 97
-  #
-  #  This method is intended for compatibility to character literals
-  #  in Ruby 1.9.
-  #
-  #  For example, <code>?a.ord</code> returns 97 both in 1.8 and 1.9.
   def ord
     self
   end
 
   #  call-seq:
-  #     int.size  ->  int
+  #    size -> integer
   #
-  #  Returns the number of bytes in the machine representation of +int+
+  #  Returns the number of bytes in the machine representation of +self+;
-  #  (machine dependent).
+  #  the value is system-dependent:
   #
   #    1.size             # => 8
   #    -1.size            # => 8
@@ -229,34 +218,35 @@ class Integer
   end
 
   #  call-seq:
-  #     int.to_i    ->  integer
+  #    to_i -> self
   #
-  #  Since +int+ is already an Integer, returns +self+.
+  #  Returns +self+ (which is already an \Integer).
   def to_i
     self
   end
 
   #  call-seq:
-  #     int.to_int  ->  integer
+  #    to_int -> self
   #
-  #  Since +int+ is already an Integer, returns +self+.
+  #  Returns +self+ (which is already an \Integer).
   def to_int
     self
   end
 
   # call-seq:
-  #    int.zero? -> true or false
+  #   zero? -> true or false
   #
-  # Returns +true+ if +int+ has a zero value.
+  # Returns +true+ if +self+ has a zero value, +false+ otherwise.
   def zero?
     Primitive.attr! :leaf
     Primitive.cexpr! 'rb_int_zero_p(self)'
   end
 
   #  call-seq:
-  #    ceildiv(other) -> integer
+  #    ceildiv(numeric) -> integer
   #
-  #  Returns the result of division +self+ by +other+. The result is rounded up to the nearest integer.
+  #  Returns the result of division +self+ by +numeric+.
+  #  rounded up to the nearest integer.
   #
   #    3.ceildiv(3)   # => 1
   #    4.ceildiv(3)   # => 2
@@ -266,48 +256,44 @@ class Integer
   #    -4.ceildiv(-3) # => 2
   #
   #    3.ceildiv(1.2) # => 3
+  #
   def ceildiv(other)
     -div(0 - other)
   end
 
   #
   # call-seq:
-  #    int.numerator  ->  self
+  #   numerator -> self
   #
-  # Returns self.
+  # Returns +self+.
   #
   def numerator
     self
   end
 
-  #
   # call-seq:
-  #    int.denominator  ->  1
+  #   denominator -> 1
-  #
-  # Returns 1.
   #
+  # Returns +1+.
   def denominator
     1
   end
 end
 
 class Float
-  #
+
   # call-seq:
-  #    float.to_f  ->  self
+  #   to_f -> self
-  #
-  # Since +float+ is already a Float, returns +self+.
   #
+  #  Returns +self+ (which is already a \Float).
   def to_f
     self
   end
 
-  #
   #  call-seq:
   #    float.abs ->  float
-  #     float.magnitude  ->  float
   #
-  #  Returns the absolute value of +float+.
+  #  Returns the absolute value of +self+:
   #
   #    (-34.56).abs # => 34.56
   #    -34.56.abs   # => 34.56
@@ -323,45 +309,38 @@ class Float
     Primitive.cexpr! 'rb_float_abs(self)'
   end
 
-  #
   # call-seq:
   #   -float -> float
   #
-  # Returns +float+, negated.
+  # Returns +self+, negated.
   #
   def -@
     Primitive.attr! :leaf
     Primitive.cexpr! 'rb_float_uminus(self)'
   end
 
-  #
   #  call-seq:
-  #     float.zero?  ->  true or false
+  #    zero? -> true or false
-  #
-  #  Returns +true+ if +float+ is 0.0.
   #
+  #  Returns +true+ if +self+ is 0.0, +false+ otherwise.
   def zero?
     Primitive.attr! :leaf
     Primitive.cexpr! 'RBOOL(FLOAT_ZERO_P(self))'
   end
 
-  #
   #  call-seq:
-  #     float.positive?  ->  true or false
+  #    positive? -> true or false
-  #
-  #  Returns +true+ if +float+ is greater than 0.
   #
+  #  Returns +true+ if +self+ is greater than 0, +false+ otherwise.
   def positive?
     Primitive.attr! :leaf
     Primitive.cexpr! 'RBOOL(RFLOAT_VALUE(self) > 0.0)'
   end
 
-  #
   #  call-seq:
-  #     float.negative?  ->  true or false
+  #    negative? -> true or false
-  #
-  #  Returns +true+ if +float+ is less than 0.
   #
+  #  Returns +true+ if +self+ is less than 0, +false+ otherwise.
   def negative?
     Primitive.attr! :leaf
     Primitive.cexpr! 'RBOOL(RFLOAT_VALUE(self) < 0.0)'