ruby-oci8 2.1.0 → 2.1.1

data/ext/oci8/ocinumber.c

@@ -2,7 +2,7 @@
 /*
  *  ocinumber.c
  *
- * Copyright (C) 2005-2011 KUBO Takehiro <kubo@jiubao.org>
+ * Copyright (C) 2005-2012 KUBO Takehiro <kubo@jiubao.org>
  *
  */
 #include "oci8.h"
@@ -112,7 +112,9 @@ static VALUE onum_s_alloc(VALUE klass)
     return obj;
 }
 
-/* construct an ruby object(OCI::Number) from C structure (OCINumber). */
+/*
+ * OCINumber (C datatype) -> OraNumber (ruby object)
+ */
 VALUE oci8_make_ocinumber(OCINumber *s, OCIError *errhp)
 {
     VALUE obj;
@@ -123,6 +125,9 @@ VALUE oci8_make_ocinumber(OCINumber *s, OCIError *errhp)
     return obj;
 }
 
+/*
+ * OCINumber (C datatype) -> Integer (ruby object)
+ */
 VALUE oci8_make_integer(OCINumber *s, OCIError *errhp)
 {
     signed long sl;
@@ -141,12 +146,17 @@ VALUE oci8_make_integer(OCINumber *s, OCIError *errhp)
     rb_raise(eOCIException, "Invalid internal number format: %s", buf);
 }
 
+/*
+ * OCINumber (C datatype) -> Float (ruby object)
+ */
 VALUE oci8_make_float(OCINumber *s, OCIError *errhp)
 {
     return rb_float_new(oci8_onum_to_dbl(s, errhp));
 }
 
-/* fill C structure (OCINumber) from a string. */
+/*
+ * String (ruby object) -> OCINumber (C datatype)
+ */
 static void set_oci_number_from_str(OCINumber *result, VALUE str, VALUE fmt, VALUE nls_params, OCIError *errhp)
 {
     oratext *fmt_ptr;
@@ -190,8 +200,11 @@ static void set_oci_number_from_str(OCINumber *result, VALUE str, VALUE fmt, VAL
                              result));
 }
 
-/* fill C structure (OCINumber) from a numeric object. */
-/* 1 - success, 0 - error */
+/*
+ * Numeric (ruby object) -> OCINumber (C datatype)
+ *
+ * @return 1 on success. Otherwise, 0.
+ */
 static int set_oci_number_from_num(OCINumber *result, VALUE num, int force, OCIError *errhp)
 {
     signed long sl;
@@ -287,6 +300,9 @@ is_not_big_decimal:
     return 0;
 }
 
+/*
+ * Numeric (ruby object) -> OCINumber (C datatype)
+ */
 OCINumber *oci8_set_ocinumber(OCINumber *result, VALUE self, OCIError *errhp)
 {
     set_oci_number_from_num(result, self, 1, errhp);
@@ -294,6 +310,9 @@ OCINumber *oci8_set_ocinumber(OCINumber *result, VALUE self, OCIError *errhp)
 }
 #define TO_OCINUM oci8_set_ocinumber
 
+/*
+ * Numeric (ruby object) -> OCINumber (C datatype) as an integer
+ */
 OCINumber *oci8_set_integer(OCINumber *result, VALUE self, OCIError *errhp)
 {
     OCINumber work;
@@ -303,6 +322,9 @@ OCINumber *oci8_set_integer(OCINumber *result, VALUE self, OCIError *errhp)
     return result;
 }
 
+/*
+ * OCINumber (C datatype) -> double (C datatype)
+ */
 double oci8_onum_to_dbl(OCINumber *s, OCIError *errhp)
 {
     if (oci8_float_conversion_type_is_ruby) {
@@ -330,14 +352,15 @@ double oci8_onum_to_dbl(OCINumber *s, OCIError *errhp)
     }
 }
 
+/*
+ * double (C datatype) -> OCINumber (C datatype)
+ */
 OCINumber *oci8_dbl_to_onum(OCINumber *result, double dbl, OCIError *errhp)
 {
-    switch (fpclassify(dbl)) {
-    case FP_NAN:
+    if (isnan(dbl)) {
         rb_raise(rb_eFloatDomainError, "NaN");
         /* never reach here */
-        break;
-    case FP_INFINITE:
+    } else if (isinf(dbl)) {
         if (dbl > 0.0) {
             oranumber_from_str(result, "~", 1);
         } else {
@@ -361,12 +384,25 @@ OCINumber *oci8_dbl_to_onum(OCINumber *result, double dbl, OCIError *errhp)
     return result;
 }
 
+/*
+ *  Document-module: OCI8::Math
+ *
+ *  The <code>OCI8::Math</code> module contains module functions for basic
+ *  trigonometric and transcendental functions. Their accuracy is
+ *  same with {OraNumber}.
+ */
+
 /*
  *  call-seq:
- *     OCI8::Math.atan2(y, x) -> oranumber
+ *    atan2(y, x)
  *
- *  Computes the arc tangent given <i>y</i> and <i>x</i>. Returns
- *  -PI..PI.
+ *  Computes the principal value of the arc tangent of <i>y/x</i>,
+ *  using the signs of both arguments to determine the quadrant of the
+ *  return value.
+ *
+ *  @param [Numeric] y
+ *  @param [Numeric] x
+ *  @return [OraNumber]  Computed value in the range [-{PI}, {PI}]
  */
 static VALUE omath_atan2(VALUE self, VALUE Ycoordinate, VALUE Xcoordinate)
 {
@@ -399,10 +435,12 @@ static VALUE omath_atan2(VALUE self, VALUE Ycoordinate, VALUE Xcoordinate)
 
 /*
  *  call-seq:
- *     OCI8::Math.cos(x) -> oranumber
+ *     cos(x)
+ *
+ *  Computes the cosine of <i>x</i>, measured in radians.
  *
- *  Computes the cosine of <i>x</i> (expressed in radians). Returns
- *  -1..1.
+ *  @param [Numeric] x
+ *  @return [OraNumber]  Computed value in the range [-1, 1]
  */
 static VALUE omath_cos(VALUE obj, VALUE radian)
 {
@@ -416,10 +454,12 @@ static VALUE omath_cos(VALUE obj, VALUE radian)
 
 /*
  *  call-seq:
- *     OCI8::Math.sin(x)    -> oranumber
+ *     sin(x)
  *
- *  Computes the sine of <i>x</i> (expressed in radians). Returns
- *  -1..1.
+ *  Computes the sine of <i>x</i>, measured in radians.
+ *
+ *  @param [Numeric] x
+ *  @return [OraNumber]  Computed value in the range [-1, 1]
  */
 static VALUE omath_sin(VALUE obj, VALUE radian)
 {
@@ -433,9 +473,12 @@ static VALUE omath_sin(VALUE obj, VALUE radian)
 
 /*
  *  call-seq:
- *     OCI8::Math.tan(x)    -> oranumber
+ *     tan(x)
+ *
+ *  Computes the tangent of <i>x</i>, measured in radians.
  *
- *  Returns the tangent of <i>x</i> (expressed in radians).
+ *  @param [Numeric] x
+ *  @return [OraNumber]
  */
 static VALUE omath_tan(VALUE obj, VALUE radian)
 {
@@ -449,9 +492,12 @@ static VALUE omath_tan(VALUE obj, VALUE radian)
 
 /*
  *  call-seq:
- *     OCI8::Math.acos(x)    -> oranumber
+ *     acos(x)
  *
- *  Computes the arc cosine of <i>x</i>. Returns 0..PI.
+ *  Computes the principal value of the arc cosine of <i>x</i>.
+ *
+ *  @param [Numeric] x
+ *  @return [OraNumber]  Computed value in the range [0, {PI}]
  */
 static VALUE omath_acos(VALUE obj, VALUE num)
 {
@@ -476,9 +522,12 @@ static VALUE omath_acos(VALUE obj, VALUE num)
 
 /*
  *  call-seq:
- *     OCI8::Math.asin(x)    -> oranumber
+ *     asin(x)
+ *
+ *  Computes the principal value of the arc sine of <i>x</i>.
  *
- *  Computes the arc sine of <i>x</i>. Returns 0..PI.
+ *  @param [Numeric] x
+ *  @return [OraNumber]  Computed value in the range [-{PI}/2, {PI}]/2]
  */
 static VALUE omath_asin(VALUE obj, VALUE num)
 {
@@ -503,9 +552,12 @@ static VALUE omath_asin(VALUE obj, VALUE num)
 
 /*
  *  call-seq:
- *     OCI8::Math.atan(x)    -> oranumber
+ *     atan(x)
  *
- *  Computes the arc tangent of <i>x</i>. Returns -{PI/2} .. {PI/2}.
+ *  Computes the principal value of the arc tangent of their argument <i>x</i>.
+ *
+ *  @param [Numeric] x
+ *  @return [OraNumber]  Computed value in the range [-{PI}/2, {PI}/2]
  */
 static VALUE omath_atan(VALUE obj, VALUE num)
 {
@@ -519,9 +571,12 @@ static VALUE omath_atan(VALUE obj, VALUE num)
 
 /*
  *  call-seq:
- *     OCI8::Math.cosh(x)    -> oranumber
+ *     cosh(x)
+ *
+ *  Computes the hyperbolic cosine of <i>x</i>.
  *
- *  Computes the hyperbolic cosine of <i>x</i> (expressed in radians).
+ *  @param [Numeric] x
+ *  @return [OraNumber]
  */
 static VALUE omath_cosh(VALUE obj, VALUE num)
 {
@@ -535,10 +590,12 @@ static VALUE omath_cosh(VALUE obj, VALUE num)
 
 /*
  *  call-seq:
- *     OCI8::Math.sinh(x)    -> oranumber
+ *     sinh(x)
  *
- *  Computes the hyperbolic sine of <i>x</i> (expressed in
- *  radians).
+ *  Computes the hyperbolic sine of <i>x</i>.
+ *
+ *  @param [Numeric] x
+ *  @return [OraNumber]
  */
 static VALUE omath_sinh(VALUE obj, VALUE num)
 {
@@ -552,10 +609,12 @@ static VALUE omath_sinh(VALUE obj, VALUE num)
 
 /*
  *  call-seq:
- *     OCI8::Math.tanh()    -> oranumber
+ *     tanh(x)
+ *
+ *  Computes the hyperbolic tangent of <i>x</i>.
  *
- *  Computes the hyperbolic tangent of <i>x</i> (expressed in
- *  radians).
+ *  @param [Numeric] x
+ *  @return [OraNumber]
  */
 static VALUE omath_tanh(VALUE obj, VALUE num)
 {
@@ -569,9 +628,12 @@ static VALUE omath_tanh(VALUE obj, VALUE num)
 
 /*
  *  call-seq:
- *     OCI8::Math.exp(x)    -> oranumber
+ *     exp(x)
  *
- *  Returns e**x.
+ *  Computes the base- <i>e</i> exponential of <i>x</i>.
+ *
+ *  @param [Numeric] x
+ *  @return [OraNumber]
  */
 static VALUE omath_exp(VALUE obj, VALUE num)
 {
@@ -584,12 +646,20 @@ static VALUE omath_exp(VALUE obj, VALUE num)
 }
 
 /*
- *  call-seq:
- *     OCI8::Math.log(numeric)    -> oranumber
- *     OCI8::Math.log(numeric, base_num)  -> oranumber
+ *  @overload log(x)
+ *
+ *    Computes the natural logarithm of <i>x</i>.
+ *
+ *    @param [Numeric] x
+ *    @return [OraNumber]
+ *
+ *  @overload log(x, y)
  *
- *  Returns the natural logarithm of <i>numeric</i> for one argument.
- *  Returns the base <i>base_num</i> logarithm of <i>numeric</i> for two arguments.
+ *    Computes the base <i>y</I> logarithm of <i>x</i>.
+ *
+ *    @param [Numeric] x
+ *    @param [Numeric] y
+ *    @return [OraNumber]
  */
 static VALUE omath_log(int argc, VALUE *argv, VALUE obj)
 {
@@ -622,9 +692,12 @@ static VALUE omath_log(int argc, VALUE *argv, VALUE obj)
 
 /*
  *  call-seq:
- *     OCI8::Math.log10(numeric)    -> oranumber
+ *     log10(x)
+ *
+ *  Computes the base 10 logarithm of <i>x</i>.
  *
- *  Returns the base 10 logarithm of <i>numeric</i>.
+ *  @param [Numeric] x
+ *  @return [OraNumber]
  */
 static VALUE omath_log10(VALUE obj, VALUE num)
 {
@@ -643,9 +716,12 @@ static VALUE omath_log10(VALUE obj, VALUE num)
 
 /*
  *  call-seq:
- *     OCI8::Math.sqrt(numeric)    -> oranumber
+ *     sqrt(x)
  *
- *  Returns the non-negative square root of <i>numeric</i>.
+ *  Computes the square root of <i>x</i>.
+ *
+ *  @param [Numeric] x
+ *  @return [OraNumber]
  */
 static VALUE omath_sqrt(VALUE obj, VALUE num)
 {
@@ -665,12 +741,39 @@ static VALUE omath_sqrt(VALUE obj, VALUE num)
     return oci8_make_ocinumber(&r, errhp);
 }
 
+/*
+ *  Document-class: OraNumber
+ *
+ *  OraNumber is a ruby representation of
+ *  {http://docs.oracle.com/cd/E11882_01/server.112/e17118/sql_elements001.htm#sthref118 Oracle NUMBER data type}.
+ *  without precision and scale designators.
+ */
 
 /*
  *  call-seq:
- *     OraNumber(obj)   -> oranumber
+ *    OraNumber(expr = nil, fmt = nil, nlsparam = nil)
+ *
+ *  Converts <i>expr</i> to a value of OraNumber. The <i>expr</i> can be a Numeric value
+ *  or a String value. If it is a String value, optional <i>fmt</i> and <i>nlsparam</i>.
+ *  is used as {http://docs.oracle.com/cd/E11882_01/server.112/e17118/functions211.htm Oracle SQL function TO_NUMBER}
+ *  does.
+ *
+ *  @example
+ *    # Numeric expr
+ *    OraNumber(123456.789)   # -> 123456.789
+ *    # String expr
+ *    OraNumber('123456.789') # -> 123456.789
+ *    # String expr with fmt
+ *    OraNumber('123,456.789', '999,999,999.999') # -> 123456.789
+ *    # String expr with fmt and nlsparam
+ *    OraNumber('123.456,789', '999G999G999D999',  "NLS_NUMERIC_CHARACTERS = ',.'") # -> 123456.789
  *
- *  Returns a new <code>OraNumber</code>.
+ *  @param [String, Numeric] expr
+ *  @param [String]          fmt
+ *  @param [String]          nlsparam
+ *  @return [OraNumber]
+ *
+ *  @since 2.0.3
  */
 static VALUE onum_f_new(int argc, VALUE *argv, VALUE self)
 {
@@ -679,6 +782,29 @@ static VALUE onum_f_new(int argc, VALUE *argv, VALUE self)
     return obj;
 }
 
+/*
+ *  call-seq:
+ *    initialize(expr = nil, fmt = nil, nlsparam = nil)
+ *
+ *  Creates a value of OraNumber from <i>expr</i>. The <i>expr</i> can be a Numeric value
+ *  or a String value. If it is a String value, optional <i>fmt</i> and <i>nlsparam</i>
+ *  is used as {http://docs.oracle.com/cd/E11882_01/server.112/e17118/functions211.htm Oracle SQL function TO_NUMBER}
+ *  does.
+ *
+ *  @example
+ *    # Numeric expr
+ *    OraNumber.new(123456.789)   # -> 123456.789
+ *    # String expr
+ *    OraNumber.new('123456.789') # => #<OraNumber:123456.789>
+ *    # String expr with fmt
+ *    OraNumber.new('123,456.789', '999,999,999.999') # => #<OraNumber:123456.789>
+ *    # String expr with fmt and nlsparam
+ *    OraNumber.new('123.456,789', '999G999G999D999', "NLS_NUMERIC_CHARACTERS = ',.'") # => #<OraNumber:123456.789>
+ *
+ *  @param [String, Numeric] expr
+ *  @param [String]          fmt
+ *  @param [String]          nlsparam
+ */
 static VALUE onum_initialize(int argc, VALUE *argv, VALUE self)
 {
     OCIError *errhp = oci8_errhp;
@@ -696,6 +822,17 @@ static VALUE onum_initialize(int argc, VALUE *argv, VALUE self)
     return Qnil;
 }
 
+/*
+ *  call-seq:
+ *    initialize_copy(obj)
+ *
+ *  Replaces <i>self</i> with <i>obj</i>. <code>Object#clone</code> and <code>Object#dup</code>
+ *  call this method to copy data unknown by the ruby interpreter.
+ *
+ *  @param [OraNumber] obj
+ *
+ *  @private
+ */
 static VALUE onum_initialize_copy(VALUE lhs, VALUE rhs)
 {
     if (!RTEST(rb_obj_is_instance_of(rhs, CLASS_OF(lhs)))) {
@@ -706,6 +843,9 @@ static VALUE onum_initialize_copy(VALUE lhs, VALUE rhs)
     return lhs;
 }
 
+/*
+ *  @private
+ */
 static VALUE onum_coerce(VALUE self, VALUE other)
 {
     signed long sl;
@@ -733,10 +873,12 @@ static VALUE onum_coerce(VALUE self, VALUE other)
 }
 
 /*
- *  call-seq:
- *     -onum   -> oranumber
+ *  Returns a negated value of <i>self</i>
+ *
+ *  @example
+ *    -OraNumber(2)  # =>  #<OraNumber:-2>
  *
- *  Returns a negated <code>OraNumber</code>.
+ *  @return [OraNumber]
  */
 static VALUE onum_neg(VALUE self)
 {
@@ -747,12 +889,20 @@ static VALUE onum_neg(VALUE self)
     return oci8_make_ocinumber(&r, errhp);
 }
 
-
 /*
  *  call-seq:
- *    onum + other    -> number
+ *    self + other
+ *
+ *  Returns the sum of <i>self</i> and <i>other</i>.
+ *  When <i>other</i>'s class is Integer, it returns an OraNumber value.
+ *  Otherwise, it returns a value same with <i>other</i>'s class.
  *
- *  Returns the sum of <i>onum</i> and <i>other</i>.
+ *  @example
+ *    OraNumber(2) + 3   # => #<OraNumber:5>
+ *    OraNumber(2) + 1.5 # => 3.5 (Float)
+ *
+ *  @param [Numeric] other
+ *  @return [Numeric]
  */
 static VALUE onum_add(VALUE lhs, VALUE rhs)
 {
@@ -783,10 +933,18 @@ static VALUE onum_add(VALUE lhs, VALUE rhs)
 
 /*
  *  call-seq:
- *    onum - integer   -> oranumber
- *    onum - numeric   -> numeric
+ *    self - other
+ *
+ *  Returns the difference of <i>self</i> and <i>other</i>.
+ *  When <i>other</i>'s class is Integer, it returns an OraNumber value.
+ *  Otherwise, it returns a value same with <i>other</i>'s class.
  *
- *  Returns the difference of <i>onum</i> and <i>other</i>.
+ *  @example
+ *    OraNumber(2) - 3   # => #<OraNumber:-1>
+ *    OraNumber(2) - 1.5 # => 0.5 (Float)
+ *
+ *  @param [Numeric] other
+ *  @return [Numeric]
  */
 static VALUE onum_sub(VALUE lhs, VALUE rhs)
 {
@@ -817,9 +975,18 @@ static VALUE onum_sub(VALUE lhs, VALUE rhs)
 
 /*
  *  call-seq:
- *    onum * other   -> number
+ *    self * other
+ *
+ *  Returns the product of <i>self</i> and <i>other</i>.
+ *  When <i>other</i>'s class is Integer, it returns an OraNumber value.
+ *  Otherwise, it returns a value same with <i>other</i>'s class.
+ *
+ *  @example
+ *    OraNumber(2) * 3   # => #<OraNumber:6>
+ *    OraNumber(2) * 1.5 # => 3.0 (Float)
  *
- *  Returns the product of <i>onum</i> and <i>other</i>.
+ *  @param [Numeric] other
+ *  @return [Numeric]
  */
 static VALUE onum_mul(VALUE lhs, VALUE rhs)
 {
@@ -850,10 +1017,18 @@ static VALUE onum_mul(VALUE lhs, VALUE rhs)
 
 /*
  *  call-seq:
- *    onum / integer   -> oranumber
- *    onum / numeric   -> numeric
+ *    self / other
+ *
+ *  Returns the result of dividing <i>self</i> by <i>other</i>.
+ *  When <i>other</i>'s class is Integer, it returns an OraNumber value.
+ *  Otherwise, it returns a value same with <i>other</i>'s class.
+ *
+ *  @example
+ *    OraNumber(2) / 3   # => #<OraNumber:0.6666666666666666666666666666666666666667>
+ *    OraNumber(2) / 1.5 # => 1.3333333333333333 (Float)
  *
- *  Returns the result of dividing <i>onum</i> by <i>other</i>.
+ *  @param [Numeric] other
+ *  @return [Numeric]
  */
 static VALUE onum_div(VALUE lhs, VALUE rhs)
 {
@@ -892,9 +1067,17 @@ static VALUE onum_div(VALUE lhs, VALUE rhs)
 
 /*
  *  call-seq:
- *    onum % other   -> oranumber
+ *    self % other
  *
- *  Returns the modulo after division of <i>onum</i> by <i>other</i>.
+ *  Returns the modulo after division of <i>self</i> by <i>other</i>.
+ *
+ *  @example
+ *    OraNumber(13) % 5 # => #<OraNumber:3>
+ *
+ *  @param [Numeric] other
+ *  @return [OraNumber]
+ *
+ *  @raise [ZeroDivisionError] when <i>other</i> is zero.
  */
 static VALUE onum_mod(VALUE lhs, VALUE rhs)
 {
@@ -917,9 +1100,16 @@ static VALUE onum_mod(VALUE lhs, VALUE rhs)
 
 /*
  *  call-seq:
- *    onum ** other   -> oranumber
+ *    self ** other
+ *
+ *  Raises <i>self</i> to the power of <i>other</i>.
  *
- *  Raises <i>onum</i> the <i>other</i> power.
+ *  @example
+ *    OraNumber(2) ** 2   # => #<OraNumber:4>
+ *    OraNumber(2) ** 2.5 # => #<OraNumber:5.65685424949238019520675489683879231435>
+ *
+ *  @param [Numeric] other
+ *  @return [OraNumber]
  */
 static VALUE onum_power(VALUE lhs, VALUE rhs)
 {
@@ -940,11 +1130,19 @@ static VALUE onum_power(VALUE lhs, VALUE rhs)
 
 /*
  *  call-seq:
- *    onum <=> other   -> -1, 0, +1
+ *    self <=> other
  *
- *  Returns -1, 0, or +1 depending on whether <i>onum</i> is less than,
+ *  Returns -1, 0, or +1 depending on whether <i>self</i> is less than,
  *  equal to, or greater than <i>other</i>. This is the basis for the
  *  tests in <code>Comparable</code>.
+ *
+ *  @example
+ *    OraNumber(5) <=> 3   # => 1
+ *    OraNumber(4) <=> 4   # => 0
+ *    OraNumber(2) <=> 2.5 # => 1
+ *
+ *  @param [Numeric] other
+ *  @return [-1, 0 or +1]
  */
 static VALUE onum_cmp(VALUE lhs, VALUE rhs)
 {
@@ -967,10 +1165,14 @@ static VALUE onum_cmp(VALUE lhs, VALUE rhs)
 }
 
 /*
- *  call-seq:
- *     onum.floor   -> integer
+ *  Returns the largest <code>Integer</code> less than or equal to <i>self</i>.
  *
- *  Returns the largest <code>Integer</code> less than or equal to <i>onum</i>.
+ *  @example
+ *    OraNumber(11.1).floor  # => 11
+ *    OraNumber(25.8).floor  # => 25
+ *    OraNumber(-25.8).floor # => -26
+ *
+ *  @return [Integer]
  */
 static VALUE onum_floor(VALUE self)
 {
@@ -982,11 +1184,14 @@ static VALUE onum_floor(VALUE self)
 }
 
 /*
- *  call-seq:
- *     onum.ceil    -> integer
+ *  Returns the smallest <code>Integer</code> greater than or equal to <i>self</i>.
  *
- *  Returns the smallest <code>Integer</code> greater than or equal to
- *  <i>onum</i>.
+ *  @example
+ *    OraNumber(11.1).ceil  # => 12
+ *    OraNumber(25.8).ceil  # => 26
+ *    OraNumber(-25.8).ceil # => -25
+ *
+ *  @return [Integer]
  */
 static VALUE onum_ceil(VALUE self)
 {
@@ -998,16 +1203,30 @@ static VALUE onum_ceil(VALUE self)
 }
 
 /*
- *  call-seq:
- *     onum.round      -> integer
- *     onum.round(decplace) -> oranumber
+ *  @overload round
  *
- *  Rounds <i>onum</i> to the nearest <code>Integer</code> when no argument.
- *  Rounds <i>onum</i> to a specified decimal place <i>decplace</i> when one argument.
+ *    Rounds <i>self</i> to the nearest <code>Integer</code>.
  *
- *   OraNumber.new(1.234).round(1)  #=> 1.2
- *   OraNumber.new(1.234).round(2)  #=> 1.23
- *   OraNumber.new(1.234).round(3)  #=> 1.234
+ *    @example
+ *      OraNumber(1.49).round     # => 1
+ *      OraNumber(1.5).round      # => 2
+ *      OraNumber(-1.49).round    # => -1
+ *      OraNumber(-1.5).round     # => -2
+ *
+ *    @return [Integer]
+ *
+ *  @overload round(decplace)
+ *
+ *    Rounds <i>onum</i> to a specified decimal place <i>decplace</i>.
+ *
+ *    @example
+ *      OraNumber(123.456).round(2)   # => #<OraNumber:123.46>
+ *      OraNumber(123.456).round(1)   # => #<OraNumber:123.5>
+ *      OraNumber(123.456).round(0)   # => #<OraNumber:123>
+ *      OraNumber(123.456).round(-1)  # => #<OraNumber:120>
+ *
+ *    @param [Integer]
+ *    @return [OraNumber]
  */
 static VALUE onum_round(int argc, VALUE *argv, VALUE self)
 {
@@ -1026,11 +1245,24 @@ static VALUE onum_round(int argc, VALUE *argv, VALUE self)
 
 /*
  *  call-seq:
- *     onum.truncate     -> integer
- *     onum.truncate(decplace) -> oranumber
+ *    truncate(decplace = 0)
  *
- *  Truncates <i>onum</i> to the <code>Integer</code> when no argument.
- *  Truncates <i>onum</i> to a specified decimal place <i>decplace</i> when one argument.
+ *  Truncates <i>self</i> to a specified decimal place <i>decplace</i>.
+ *
+ *  @example
+ *    OraNumber(123.456).truncate      # => #<OraNumber:123>
+ *    OraNumber(123.456).truncate(1)   # => #<OraNumber:123.4>
+ *    OraNumber(123.456).truncate(2)   # => #<OraNumber:123.45>
+ *    OraNumber(123.456).truncate(-1)  # => #<OraNumber:120>
+ *    
+ *    OraNumber(-123.456).truncate     # => #<OraNumber:-123>
+ *    OraNumber(-123.456).truncate(1)  # => #<OraNumber:-123.4>
+ *    OraNumber(-123.456).truncate(2)  # => #<OraNumber:-123.45>
+ *    OraNumber(-123.456).truncate(-1) # => #<OraNumber:-120>
+ *
+ *  @param [Integer]
+ *  @return [OraNumber]
+ *  @todo returns {Integer} when <i>decplace</i> is not specified.
  */
 static VALUE onum_trunc(int argc, VALUE *argv, VALUE self)
 {
@@ -1045,14 +1277,17 @@ static VALUE onum_trunc(int argc, VALUE *argv, VALUE self)
 
 /*
  *  call-seq:
- *     onum.round_prec(digits) -> oranumber
+ *     round_prec(digits)
  *
- *  Rounds <i>onum</i> to a specified number of decimal digits.
+ *  Rounds <i>self</i> to a specified number of decimal digits.
  *  This method is available on Oracle 8.1 client or upper.
  *
- *   OraNumber.new(1.234).round_prec(2)  #=> 1.2
- *   OraNumber.new(12.34).round_prec(2)  #=> 12
- *   OraNumber.new(123.4).round_prec(2)  #=> 120
+ *  @example
+ *    OraNumber(1.234).round_prec(2) # => #<OraNumber:1.2>
+ *    OraNumber(12.34).round_prec(2) # => #<OraNumber:12>
+ *    OraNumber(123.4).round_prec(2) # => #<OraNumber:120>
+ *
+ *  @return [OraNumber]
  */
 static VALUE onum_round_prec(VALUE self, VALUE ndigs)
 {
@@ -1065,11 +1300,20 @@ static VALUE onum_round_prec(VALUE self, VALUE ndigs)
 
 /*
  *  call-seq:
- *     onum.to_char(fmt = nil, nls_params = nil)  -> string
+ *     onum.to_char(fmt = nil, nlsparam = nil)
  *
  *  Returns a string containing a representation of self.
- *  <i>fmt</i> and <i>nls_params</i> are same meanings with
- *  <code>TO_CHAR</code> of Oracle function.
+ *  <i>fmt</i> and <i>nlsparam</i> are used as 
+ *  {http://docs.oracle.com/cd/E11882_01/server.112/e17118/functions201.htm Oracle SQL function TO_CHAR(number)}
+ *  does.
+ *
+ *  @example
+ *    OraNumber(123456.789).to_char('FM999,999,999.999')  # => "123,456.789"
+ *    OraNumber(123456.789).to_char('FM999G999G999D999',  "NLS_NUMERIC_CHARACTERS = ',.'") # => "123.456,789"
+ *
+ *  @param [String] fmt
+ *  @param [String] nlsparam
+ *  @return [String]
  */
 static VALUE onum_to_char(int argc, VALUE *argv, VALUE self)
 {
@@ -1121,10 +1365,11 @@ static VALUE onum_to_char(int argc, VALUE *argv, VALUE self)
 }
 
 /*
- *  call-seq:
- *     onum.to_s    -> string
- *
  *  Returns a string containing a representation of self.
+ *
+ *  @return [String]
+ *
+ *  @see #to_char
  */
 static VALUE onum_to_s(VALUE self)
 {
@@ -1132,10 +1377,9 @@ static VALUE onum_to_s(VALUE self)
 }
 
 /*
- *  call-seq:
- *     onum.to_i       -> integer
+ *  Returns <i>self</i> truncated to an <code>Integer</code>.
  *
- *  Returns <i>onum</i> truncated to an <code>Integer</code>.
+ *  @return [Integer]
  */
 static VALUE onum_to_i(VALUE self)
 {
@@ -1147,11 +1391,14 @@ static VALUE onum_to_i(VALUE self)
 }
 
 /*
- *  call-seq:
- *     onum.to_f -> float
+ *  Converts <i>self</i> to <code>Float</code>.
  *
- *  Return the value as a <code>Float</code>.
+ *  When {OCI8.properties OCI8.properties [:float_conversion_type\]}
+ *  is <code>:ruby</code>, <i>self</I> is converted by <code>self.to_s.to_f</code>.
+ *  When it is <code>:oracle</code>, <i>self</I> is converted by the Oracle
+ *  OCI function OCINumberToReal().
  *
+ *  @return [Float]
  */
 static VALUE onum_to_f(VALUE self)
 {
@@ -1159,11 +1406,9 @@ static VALUE onum_to_f(VALUE self)
 }
 
 /*
- *  call-seq:
- *     onum.to_r -> rational
- *
- *  Return the value as a <code>Rational</code>.
+ *  Returns <i>self</i> as a <code>Rational</code>.
  *
+ *  @return [Rational]
  */
 static VALUE onum_to_r(VALUE self)
 {
@@ -1202,11 +1447,9 @@ static VALUE onum_to_r(VALUE self)
 }
 
 /*
- *  call-seq:
- *     onum.to_d -> bigdecimal
- *
- *  Return the value as a <code>BigDecimal</code>.
+ *  Returns <i>self</i> as a <code>BigDecimal</code>.
  *
+ *  @return [BigDecimal]
  */
 static VALUE onum_to_d(VALUE self)
 {
@@ -1230,13 +1473,14 @@ static VALUE onum_to_d_real(OCINumber *num, OCIError *errhp)
 }
 
 /*
- *  call-seq:
- *     onum.has_decimal_part? -> true or false
- *
- *  Returns +true+ if <i>self</i> has a decimal part.
+ *  Returns <code>true</code> if <i>self</i> has a decimal part.
  *
+ *  @example
  *    OraNumber(10).has_decimal_part?   # => false
  *    OraNumber(10.1).has_decimal_part? # => true
+ *
+ *  @return [true or false]
+ *  @since 2.0.5
  */
 static VALUE onum_has_decimal_part_p(VALUE self)
 {
@@ -1248,11 +1492,9 @@ static VALUE onum_has_decimal_part_p(VALUE self)
 }
 
 /*
- *  call-seq:
- *     onum.to_onum -> oranumber
- *
  *  Returns self.
  *
+ *  @return [OraNumber]
  */
 static VALUE onum_to_onum(VALUE self)
 {
@@ -1260,11 +1502,9 @@ static VALUE onum_to_onum(VALUE self)
 }
 
 /*
- *  call-seq:
- *     onum.zero?    -> true or false
- *
- *  Returns <code>true</code> if <i>onum</i> is zero.
+ *  Returns <code>true</code> if <i>self</i> is zero.
  *
+ *  @return [true or false]
  */
 static VALUE onum_zero_p(VALUE self)
 {
@@ -1276,11 +1516,9 @@ static VALUE onum_zero_p(VALUE self)
 }
 
 /*
- *  call-seq:
- *     onum.abs -> oranumber
- *
- *  Returns the absolute value of <i>onum</i>.
+ *  Returns the absolute value of <i>self</i>.
  *
+ *  @return [OraNumber]
  */
 static VALUE onum_abs(VALUE self)
 {
@@ -1293,10 +1531,16 @@ static VALUE onum_abs(VALUE self)
 
 /*
  *  call-seq:
- *     onum.shift(fixnum)    -> oranumber
+ *     shift(ndigits)
  *
- *  Returns <i>onum</i> * 10**<i>fixnum</i>
+ *  Returns <i>self</i> shifted by <i>ndigits</i>
  *  This method is available on Oracle 8.1 client or upper.
+ *
+ *  @example
+ *     OraNumber(123).shift(3)  # => #<OraNumber:123000>
+ *     OraNumber(123).shift(-3) # => #<OraNumber:0.123>
+ *
+ *  @return [OraNumber]
  */
 static VALUE onum_shift(VALUE self, VALUE exp)
 {
@@ -1308,15 +1552,16 @@ static VALUE onum_shift(VALUE self, VALUE exp)
 }
 
 /*
- *  call-seq:
- *     onum.dump    -> string
+ *  Returns internal representation whose format is same with the return value of
+ *  {http://docs.oracle.com/cd/E11882_01/server.112/e17118/functions055.htm Oracle SQL function DUMP}.
  *
- *  Returns internal representation whose format is same with
- *  the return value of Oracle SQL function DUMP().
+ *  @example
+ *    OraNumber.new(100).dump  #=> "Typ=2 Len=2: 194,2"
+ *    OraNumber.new(123).dump  #=> "Typ=2 Len=3: 194,2,24"
+ *    OraNumber.new(0.1).dump  #=> "Typ=2 Len=2: 192,11"
  *
- *   OraNumber.new(100).dump  #=> "Typ=2 Len=2: 194,2"
- *   OraNumber.new(123).dump  #=> "Typ=2 Len=3: 194,2,24"
- *   OraNumber.new(0.1).dump  #=> "Typ=2 Len=2: 192,11"
+ *  @return [String]
+ *  @since 2.0.4
  */
 static VALUE onum_dump(VALUE self)
 {
@@ -1325,6 +1570,9 @@ static VALUE onum_dump(VALUE self)
     return rb_usascii_str_new(buf, rv);
 }
 
+/*
+ *  @private
+ */
 static VALUE onum_hash(VALUE self)
 {
     char *c  = DATA_PTR(self);
@@ -1342,6 +1590,9 @@ static VALUE onum_hash(VALUE self)
     return INT2FIX(hash);
 }
 
+/*
+ *  @private
+ */
 static VALUE onum_inspect(VALUE self)
 {
     const char *name = rb_class2name(CLASS_OF(self));
@@ -1356,9 +1607,13 @@ static VALUE onum_inspect(VALUE self)
 
 /*
  *  call-seq:
- *    onum._dump   -> string
+ *    _dump
  *
- *  Dump <i>onum</i> for marshaling.
+ *  Serializes <i>self</i>.
+ *  This method is called by Marshal.dump().
+ *
+ *  @return [String] a byte stream
+ *  @see OraNumber._load
  */
 static VALUE onum__dump(int argc, VALUE *argv, VALUE self)
 {
@@ -1372,9 +1627,14 @@ static VALUE onum__dump(int argc, VALUE *argv, VALUE self)
 
 /*
  *  call-seq:
- *    OraNumber._load(string)   -> oranumber
+ *    _load(bytes)
+ *
+ *  Restores a byte stream serialized by {OraNumber#_dump}.
+ *  This method is called by Marshal.load() to deserialize a byte stream
+ *  created by Marshal.dump().
  *
- *  Unmarshal a dumped <code>OraNumber</code> object.
+ *  @param [String] bytes a byte stream
+ *  @return [OraNumber] an deserialized object
  */
 static VALUE
 onum_s_load(VALUE klass, VALUE str)
@@ -1395,8 +1655,17 @@ onum_s_load(VALUE klass, VALUE str)
 }
 
 /*
- * bind_ocinumber
+ *  Document-class: OCI8::BindType::OraNumber
+ */
+
+/*
+ *  Document-class: OCI8::BindType::Integer
+ */
+
+/*
+ *  Document-class: OCI8::BindType::Float
  */
+
 static VALUE bind_ocinumber_get(oci8_bind_t *obind, void *data, void *null_struct)
 {
     return oci8_make_ocinumber((OCINumber*)data, oci8_errhp);
@@ -1555,10 +1824,10 @@ Init_oci_number(VALUE cOCI8, OCIError *errhp)
     rb_define_alloc_func(cOCINumber, onum_s_alloc);
 
     /* methods of OCI::Number */
-    rb_define_method(rb_cObject, "OraNumber", onum_f_new, -1);
-    rb_define_method_nodoc(cOCINumber, "initialize", onum_initialize, -1);
-    rb_define_method_nodoc(cOCINumber, "initialize_copy", onum_initialize_copy, 1);
-    rb_define_method_nodoc(cOCINumber, "coerce", onum_coerce, 1);
+    rb_define_global_function("OraNumber", onum_f_new, -1);
+    rb_define_method(cOCINumber, "initialize", onum_initialize, -1);
+    rb_define_method(cOCINumber, "initialize_copy", onum_initialize_copy, 1);
+    rb_define_method(cOCINumber, "coerce", onum_coerce, 1);
 
     rb_include_module(cOCINumber, rb_mComparable);
 
@@ -1584,15 +1853,15 @@ Init_oci_number(VALUE cOCI8, OCIError *errhp)
     rb_define_method(cOCINumber, "to_r", onum_to_r, 0);
     rb_define_method(cOCINumber, "to_d", onum_to_d, 0);
     rb_define_method(cOCINumber, "has_decimal_part?", onum_has_decimal_part_p, 0);
-    rb_define_method_nodoc(cOCINumber, "to_onum", onum_to_onum, 0);
+    rb_define_method(cOCINumber, "to_onum", onum_to_onum, 0);
 
     rb_define_method(cOCINumber, "zero?", onum_zero_p, 0);
     rb_define_method(cOCINumber, "abs", onum_abs, 0);
     rb_define_method(cOCINumber, "shift", onum_shift, 1);
     rb_define_method(cOCINumber, "dump", onum_dump, 0);
 
-    rb_define_method_nodoc(cOCINumber, "hash", onum_hash, 0);
-    rb_define_method_nodoc(cOCINumber, "inspect", onum_inspect, 0);
+    rb_define_method(cOCINumber, "hash", onum_hash, 0);
+    rb_define_method(cOCINumber, "inspect", onum_inspect, 0);
 
     /* methods for marshaling */
     rb_define_method(cOCINumber, "_dump", onum__dump, -1);
@@ -1601,8 +1870,22 @@ Init_oci_number(VALUE cOCI8, OCIError *errhp)
     oci8_define_bind_class("OraNumber", &bind_ocinumber_vtable);
     oci8_define_bind_class("Integer", &bind_integer_vtable);
     oci8_define_bind_class("Float", &bind_float_vtable);
+
+#if 0 /* for rdoc/yard */
+    oci8_cOCIHandle = rb_define_class("OCIHandle", rb_cObject);
+    cOCI8 = rb_define_class("OCI8", oci8_cOCIHandle);
+    mOCI8BindType = rb_define_module_under(cOCI8, "BindType");
+    cOCI8BindTypeBase = rb_define_class_under(mOCI8BindType, "Base", oci8_cOCIHandle);
+
+    dummy1 = rb_define_class_under(mOCI8BindType, "OraNumber", cOCI8BindTypeBase);
+    dummy2 = rb_define_class_under(mOCI8BindType, "Integer", cOCI8BindTypeBase);
+    dummy3 = rb_define_class_under(mOCI8BindType, "Float", cOCI8BindTypeBase);
+#endif
 }
 
+/*
+ * OraNumber (ruby object) -> OCINumber (C datatype)
+ */
 OCINumber *oci8_get_ocinumber(VALUE num)
 {
     if (!rb_obj_is_kind_of(num, cOCINumber)) {