harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r767497 [1/2] - /harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/
Date Wed, 22 Apr 2009 12:54:04 GMT
Author: tellison
Date: Wed Apr 22 12:54:03 2009
New Revision: 767497

URL: http://svn.apache.org/viewvc?rev=767497&view=rev
Log:
Apply slightly modified patch for HARMONY-6161 (Javadocs for java.math.*)

The modifications were further comment tidy-up, including removing author tags and some useless comments (e.g. "constructors").
No functional changes.

Modified:
    harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/BigDecimal.java
    harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/BigInteger.java
    harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/BitLevel.java
    harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/Conversion.java
    harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/Division.java
    harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/Elementary.java
    harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/Logical.java
    harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/MathContext.java
    harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/Multiplication.java
    harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/Primality.java
    harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/RoundingMode.java

Modified: harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/BigDecimal.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/BigDecimal.java?rev=767497&r1=767496&r2=767497&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/BigDecimal.java (original)
+++ harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/BigDecimal.java Wed Apr 22 12:54:03 2009
@@ -25,48 +25,95 @@
 import org.apache.harmony.math.internal.nls.Messages;
 
 /**
- * @author Intel Middleware Product Division
- * @author Instituto Tecnologico de Cordoba
+ * This class represents immutable arbitrary precision decimal numbers. Each
+ * {@code BigDecimal} instance is represented with a unscaled arbitrary
+ * precision mantissa (the unscaled value) and a scale. The value of the {@code
+ * BigDecimal} is {@code unscaledValue} 10^(-{@code scale}).
  */
 public class BigDecimal extends Number implements Comparable<BigDecimal>, Serializable {
-    /* Static Fields */
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * The constant zero as a {@code BigDecimal}.
+     */
     public static final BigDecimal ZERO = new BigDecimal(0, 0);
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * The constant one as a {@code BigDecimal}.
+     */
     public static final BigDecimal ONE = new BigDecimal(1, 0);
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * The constant ten as a {@code BigDecimal}.
+     */
     public static final BigDecimal TEN = new BigDecimal(10, 0);
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Rounding mode where positive values are rounded towards positive infinity
+     * and negative values towards negative infinity.
+     *
+     * @see RoundingMode#UP
+     */
     public static final int ROUND_UP = 0;
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Rounding mode where the values are rounded towards zero.
+     *
+     * @see RoundingMode#DOWN
+     */
     public static final int ROUND_DOWN = 1;
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Rounding mode to round towards positive infinity. For positive values
+     * this rounding mode behaves as {@link #ROUND_UP}, for negative values as
+     * {@link #ROUND_DOWN}.
+     *
+     * @see RoundingMode#CEILING
+     */
     public static final int ROUND_CEILING = 2;
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Rounding mode to round towards negative infinity. For positive values
+     * this rounding mode behaves as {@link #ROUND_DOWN}, for negative values as
+     * {@link #ROUND_UP}.
+     *
+     * @see RoundingMode#FLOOR
+     */
     public static final int ROUND_FLOOR = 3;
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Rounding mode where values are rounded towards the nearest neighbor.
+     * Ties are broken by rounding up.
+     *
+     * @see RoundingMode#HALF_UP
+     */
     public static final int ROUND_HALF_UP = 4;
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Rounding mode where values are rounded towards the nearest neighbor.
+     * Ties are broken by rounding down.
+     *
+     * @see RoundingMode#HALF_DOWN
+     */
     public static final int ROUND_HALF_DOWN = 5;
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Rounding mode where values are rounded towards the nearest neighbor.
+     * Ties are broken by rounding to the even neighbor.
+     *
+     * @see RoundingMode#HALF_EVEN
+     */
     public static final int ROUND_HALF_EVEN = 6;
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Rounding mode where the rounding operations throws an {@code
+     * ArithmeticException} for the case that rounding is necessary, i.e. for
+     * the case that the value cannot be represented exactly.
+     *
+     * @see RoundingMode#UNNECESSARY
+     */
     public static final int ROUND_UNNECESSARY = 7;
 
-    /* Private Fields */
-
-    /** @ar.org.fitc.spec_ref */
+    /** This is the serialVersionUID used by the sun implementation. */
     private static final long serialVersionUID = 6108874887143696463L;
 
     /** The double closer to <code>Log10(2)</code>. */
@@ -74,24 +121,25 @@
 
     /** The <code>String</code> representation is cached. */
     private transient String toStringImage = null;
-    
+
+    /** Cache for the hash code. */
     private transient int hashCode = 0;
 
     /**
      * An array with powers of five that fit in the type <code>long</code>
-     * (<code>5^0,5^1,...,5^27</code>)
+     * (<code>5^0,5^1,...,5^27</code>).
      */
     private static final BigInteger FIVE_POW[];
 
     /**
      * An array with powers of ten that fit in the type <code>long</code>
-     * (<code>10^0,10^1,...,10^18</code>)
+     * (<code>10^0,10^1,...,10^18</code>).
      */
     private static final BigInteger TEN_POW[];
 
     /**
      * An array with powers of ten that fit in the type <code>long</code>
-     * (<code>10^0,10^1,...,10^18</code>)
+     * (<code>10^0,10^1,...,10^18</code>).
      */
     private static final long[] LONG_TEN_POW = new long[]
     {   1L,
@@ -149,15 +197,16 @@
     private static final int[] LONG_TEN_POW_BIT_LENGTH = new int[LONG_TEN_POW.length];
     
     private static final int BI_SCALED_BY_ZERO_LENGTH = 11;
+
     /**
      * An array with the first <code>BigInteger</code> scaled by zero.
-     * (<code>[0,0],[1,0],...,[10,0]</code>)
+     * (<code>[0,0],[1,0],...,[10,0]</code>).
      */
     private static final BigDecimal BI_SCALED_BY_ZERO[] = new BigDecimal[BI_SCALED_BY_ZERO_LENGTH];
 
     /**
      * An array with the zero number scaled by the first positive scales.
-     * (<code>0*10^0, 0*10^1, ..., 0*10^10</code>)
+     * (<code>0*10^0, 0*10^1, ..., 0*10^10</code>).
      */
     private static final BigDecimal ZERO_SCALED_BY[] = new BigDecimal[11];
 
@@ -191,7 +240,7 @@
 
     /**
      * The arbitrary precision integer (unscaled value) in the internal
-     * representation of <code>BigDecimal</code>.
+     * representation of {@code BigDecimal}.
      */
     private BigInteger intVal;
     
@@ -200,22 +249,21 @@
     private transient long smallValue;
 
     /** 
-     * The 32-bit integer scale in the internal representation of <code>BigDecimal</code>. 
+     * The 32-bit integer scale in the internal representation of {@code BigDecimal}.
      */
     private int scale;
 
     /**
-     * Represent the number of decimal digits in the unscaled value. This 
-     * precision is calculated the first time, and used in the following 
-     * calls of method <code>precision()</code>. Note that some call to 
-     * the private method <code>inplaceRound()</code> could update this field.
+     * Represent the number of decimal digits in the unscaled value. This
+     * precision is calculated the first time, and used in the following calls
+     * of method <code>precision()</code>. Note that some call to the private
+     * method <code>inplaceRound()</code> could update this field.
+     *
      * @see #precision()
      * @see #inplaceRound(MathContext)
      */
     private transient int precision = 0;
 
-    /* Constructors */
-
     private BigDecimal(long smallValue, int scale){
         this.smallValue = smallValue;
         this.scale = scale;
@@ -227,9 +275,27 @@
         this.scale = scale;
         this.bitLength = bitLength(smallValue);
     }
-    
-    
-    /** @ar.org.fitc.spec_ref */
+
+    /**
+     * Constructs a new {@code BigDecimal} instance from a string representation
+     * given as a character array.
+     *
+     * @param in
+     *            array of characters containing the string representation of
+     *            this {@code BigDecimal}.
+     * @param offset
+     *            first index to be copied.
+     * @param len
+     *            number of characters to be used.
+     * @throws NullPointerException
+     *             if {@code in == null}.
+     * @throws NumberFormatException
+     *             if {@code offset < 0} or {@code len <= 0} or {@code
+     *             offset+len-1 < 0} or {@code offset+len-1 >= in.length}.
+     * @throws NumberFormatException
+     *             if in does not contain a valid string representation of a big
+     *             decimal.
+     */
     public BigDecimal(char[] in, int offset, int len) {
         int begin = offset; // first index to be copied
         int last = offset + (len - 1); // last index to be copied
@@ -256,12 +322,12 @@
         for (; (offset <= last) && (in[offset] != '.')
         && (in[offset] != 'e') && (in[offset] != 'E'); offset++) {
             if (!wasNonZero) {
-            	if (in[offset] == '0') {
-            		counter++;
-            	} else {
-            	    wasNonZero = true;	
-            	}            	
-            };
+                if (in[offset] == '0') {
+                    counter++;
+                } else {
+                    wasNonZero = true;
+                }
+            }
 
         }
         unscaledBuffer.append(in, begin, offset - begin);
@@ -273,13 +339,13 @@
             begin = offset;
             for (; (offset <= last) && (in[offset] != 'e')
             && (in[offset] != 'E'); offset++) {
-            	if (!wasNonZero) {
-                	if (in[offset] == '0') {
-                		counter++;
-                	} else {
-                	    wasNonZero = true;	
-                	}            	
-                };
+                if (!wasNonZero) {
+                    if (in[offset] == '0') {
+                        counter++;
+                    } else {
+                        wasNonZero = true;
+                    }
+                }
             }
             scale = offset - begin;
             bufLength +=scale;
@@ -310,8 +376,8 @@
         }
         // Parsing the unscaled value
         if (bufLength < 19) {
-        	smallValue = Long.parseLong(unscaledBuffer.toString());
-        	bitLength = bitLength(smallValue);
+            smallValue = Long.parseLong(unscaledBuffer.toString());
+            bitLength = bitLength(smallValue);
         } else {
             setUnscaledValue(new BigInteger(unscaledBuffer.toString()));
         }        
@@ -321,35 +387,132 @@
         }    
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Constructs a new {@code BigDecimal} instance from a string representation
+     * given as a character array.
+     *
+     * @param in
+     *            array of characters containing the string representation of
+     *            this {@code BigDecimal}.
+     * @param offset
+     *            first index to be copied.
+     * @param len
+     *            number of characters to be used.
+     * @param mc
+     *            rounding mode and precision for the result of this operation.
+     * @throws NullPointerException
+     *             if {@code in == null}.
+     * @throws NumberFormatException
+     *             if {@code offset < 0} or {@code len <= 0} or {@code
+     *             offset+len-1 < 0} or {@code offset+len-1 >= in.length}.
+     * @throws NumberFormatException
+     *             if {@code in} does not contain a valid string representation
+     *             of a big decimal.
+     * @throws ArithmeticException
+     *             if {@code mc.precision > 0} and {@code mc.roundingMode ==
+     *             UNNECESSARY} and the new big decimal cannot be represented
+     *             within the given precision without rounding.
+     */
     public BigDecimal(char[] in, int offset, int len, MathContext mc) {
         this(in, offset, len);
         inplaceRound(mc);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Constructs a new {@code BigDecimal} instance from a string representation
+     * given as a character array.
+     *
+     * @param in
+     *            array of characters containing the string representation of
+     *            this {@code BigDecimal}.
+     * @throws NullPointerException
+     *             if {@code in == null}.
+     * @throws NumberFormatException
+     *             if {@code in} does not contain a valid string representation
+     *             of a big decimal.
+     */
     public BigDecimal(char[] in) {
         this(in, 0, in.length);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Constructs a new {@code BigDecimal} instance from a string representation
+     * given as a character array. The result is rounded according to the
+     * specified math context.
+     *
+     * @param in
+     *            array of characters containing the string representation of
+     *            this {@code BigDecimal}.
+     * @param mc
+     *            rounding mode and precision for the result of this operation.
+     * @throws NullPointerException
+     *             if {@code in == null}.
+     * @throws NumberFormatException
+     *             if {@code in} does not contain a valid string representation
+     *             of a big decimal.
+     * @throws ArithmeticException
+     *             if {@code mc.precision > 0} and {@code mc.roundingMode ==
+     *             UNNECESSARY} and the new big decimal cannot be represented
+     *             within the given precision without rounding.
+     */
     public BigDecimal(char[] in, MathContext mc) {
         this(in, 0, in.length);
         inplaceRound(mc);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Constructs a new {@code BigDecimal} instance from a string
+     * representation.
+     *
+     * @param val
+     *            string containing the string representation of this {@code
+     *            BigDecimal}.
+     * @throws NumberFormatException
+     *             if {@code val} does not contain a valid string representation
+     *             of a big decimal.
+     */
     public BigDecimal(String val) {
         this(val.toCharArray(), 0, val.length());
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Constructs a new {@code BigDecimal} instance from a string
+     * representation. The result is rounded according to the specified math
+     * context.
+     *
+     * @param val
+     *            string containing the string representation of this {@code
+     *            BigDecimal}.
+     * @param mc
+     *            rounding mode and precision for the result of this operation.
+     * @throws NumberFormatException
+     *             if {@code val} does not contain a valid string representation
+     *             of a big decimal.
+     * @throws ArithmeticException
+     *             if {@code mc.precision > 0} and {@code mc.roundingMode ==
+     *             UNNECESSARY} and the new big decimal cannot be represented
+     *             within the given precision without rounding.
+     */
     public BigDecimal(String val, MathContext mc) {
         this(val.toCharArray(), 0, val.length());
         inplaceRound(mc);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Constructs a new {@code BigDecimal} instance from the 64bit double
+     * {@code val}. The constructed big decimal is equivalent to the given
+     * double. For example, {@code new BigDecimal(0.1)} is equal to {@code
+     * 0.1000000000000000055511151231257827021181583404541015625}. This happens
+     * as {@code 0.1} cannot be represented exactly in binary.
+     * <p>
+     * To generate a big decimal instance which is equivalent to {@code 0.1} use
+     * the {@code BigDecimal(String)} constructor.
+     *
+     * @param val
+     *            double value to be converted to a {@code BigDecimal} instance.
+     * @throws NumberFormatException
+     *             if {@code val} is infinity or not a number.
+     */
     public BigDecimal(double val) {
         if (Double.isInfinite(val) || Double.isNaN(val)) {
             // math.03=Infinity or NaN
@@ -401,24 +564,76 @@
         }
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Constructs a new {@code BigDecimal} instance from the 64bit double
+     * {@code val}. The constructed big decimal is equivalent to the given
+     * double. For example, {@code new BigDecimal(0.1)} is equal to {@code
+     * 0.1000000000000000055511151231257827021181583404541015625}. This happens
+     * as {@code 0.1} cannot be represented exactly in binary.
+     * <p>
+     * To generate a big decimal instance which is equivalent to {@code 0.1} use
+     * the {@code BigDecimal(String)} constructor.
+     *
+     * @param val
+     *            double value to be converted to a {@code BigDecimal} instance.
+     * @param mc
+     *            rounding mode and precision for the result of this operation.
+     * @throws NumberFormatException
+     *             if {@code val} is infinity or not a number.
+     * @throws ArithmeticException
+     *             if {@code mc.precision > 0} and {@code mc.roundingMode ==
+     *             UNNECESSARY} and the new big decimal cannot be represented
+     *             within the given precision without rounding.
+     */
     public BigDecimal(double val, MathContext mc) {
         this(val);
         inplaceRound(mc);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Constructs a new {@code BigDecimal} instance from the given big integer
+     * {@code val}. The scale of the result is {@code 0}.
+     *
+     * @param val
+     *            {@code BigInteger} value to be converted to a {@code
+     *            BigDecimal} instance.
+     */
     public BigDecimal(BigInteger val) {
         this(val, 0);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Constructs a new {@code BigDecimal} instance from the given big integer
+     * {@code val}. The scale of the result is {@code 0}.
+     *
+     * @param val
+     *            {@code BigInteger} value to be converted to a {@code
+     *            BigDecimal} instance.
+     * @param mc
+     *            rounding mode and precision for the result of this operation.
+     * @throws ArithmeticException
+     *             if {@code mc.precision > 0} and {@code mc.roundingMode ==
+     *             UNNECESSARY} and the new big decimal cannot be represented
+     *             within the given precision without rounding.
+     */
     public BigDecimal(BigInteger val, MathContext mc) {
         this(val);
         inplaceRound(mc);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Constructs a new {@code BigDecimal} instance from a given unscaled value
+     * {@code unscaledVal} and a given scale. The value of this instance is
+     * {@code unscaledVal} 10^(-{@code scale}).
+     *
+     * @param unscaledVal
+     *            {@code BigInteger} representing the unscaled value of this
+     *            {@code BigDecimal} instance.
+     * @param scale
+     *            scale of this {@code BigDecimal} instance.
+     * @throws NullPointerException
+     *             if {@code unscaledVal == null}.
+     */
     public BigDecimal(BigInteger unscaledVal, int scale) {
         if (unscaledVal == null) {
             throw new NullPointerException();
@@ -427,29 +642,86 @@
         setUnscaledValue(unscaledVal);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Constructs a new {@code BigDecimal} instance from a given unscaled value
+     * {@code unscaledVal} and a given scale. The value of this instance is
+     * {@code unscaledVal} 10^(-{@code scale}). The result is rounded according
+     * to the specified math context.
+     *
+     * @param unscaledVal
+     *            {@code BigInteger} representing the unscaled value of this
+     *            {@code BigDecimal} instance.
+     * @param scale
+     *            scale of this {@code BigDecimal} instance.
+     * @param mc
+     *            rounding mode and precision for the result of this operation.
+     * @throws ArithmeticException
+     *             if {@code mc.precision > 0} and {@code mc.roundingMode ==
+     *             UNNECESSARY} and the new big decimal cannot be represented
+     *             within the given precision without rounding.
+     * @throws NullPointerException
+     *             if {@code unscaledVal == null}.
+     */
     public BigDecimal(BigInteger unscaledVal, int scale, MathContext mc) {
         this(unscaledVal, scale);
         inplaceRound(mc);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Constructs a new {@code BigDecimal} instance from the given int
+     * {@code val}. The scale of the result is 0.
+     *
+     * @param val
+     *            int value to be converted to a {@code BigDecimal} instance.
+     */
     public BigDecimal(int val) {
         this(val,0);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Constructs a new {@code BigDecimal} instance from the given int {@code
+     * val}. The scale of the result is {@code 0}. The result is rounded
+     * according to the specified math context.
+     *
+     * @param val
+     *            int value to be converted to a {@code BigDecimal} instance.
+     * @param mc
+     *            rounding mode and precision for the result of this operation.
+     * @throws ArithmeticException
+     *             if {@code mc.precision > 0} and {@code c.roundingMode ==
+     *             UNNECESSARY} and the new big decimal cannot be represented
+     *             within the given precision without rounding.
+     */
     public BigDecimal(int val, MathContext mc) {
         this(val,0);
         inplaceRound(mc);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Constructs a new {@code BigDecimal} instance from the given long {@code
+     * val}. The scale of the result is {@code 0}.
+     *
+     * @param val
+     *            long value to be converted to a {@code BigDecimal} instance.
+     */
     public BigDecimal(long val) {
         this(val,0);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Constructs a new {@code BigDecimal} instance from the given long {@code
+     * val}. The scale of the result is {@code 0}. The result is rounded
+     * according to the specified math context.
+     *
+     * @param val
+     *            long value to be converted to a {@code BigDecimal} instance.
+     * @param mc
+     *            rounding mode and precision for the result of this operation.
+     * @throws ArithmeticException
+     *             if {@code mc.precision > 0} and {@code mc.roundingMode ==
+     *             UNNECESSARY} and the new big decimal cannot be represented
+     *             within the given precision without rounding.
+     */
     public BigDecimal(long val, MathContext mc) {
         this(val);
         inplaceRound(mc);
@@ -457,7 +729,19 @@
 
     /* Public Methods */
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} instance whose value is equal to {@code
+     * unscaledVal} 10^(-{@code scale}). The scale of the result is {@code
+     * scale}, and its unscaled value is {@code unscaledVal}.
+     *
+     * @param unscaledVal
+     *            unscaled value to be used to construct the new {@code
+     *            BigDecimal}.
+     * @param scale
+     *            scale to be used to construct the new {@code BigDecimal}.
+     * @return {@code BigDecimal} instance with the value {@code unscaledVal}*
+     *         10^(-{@code unscaledVal}).
+     */
     public static BigDecimal valueOf(long unscaledVal, int scale) {
         if (scale == 0) {
             return valueOf(unscaledVal);
@@ -469,7 +753,15 @@
         return new BigDecimal(unscaledVal, scale);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} instance whose value is equal to {@code
+     * unscaledVal}. The scale of the result is {@code 0}, and its unscaled
+     * value is {@code unscaledVal}.
+     *
+     * @param unscaledVal
+     *            value to be converted to a {@code BigDecimal}.
+     * @return {@code BigDecimal} instance with the value {@code unscaledVal}.
+     */
     public static BigDecimal valueOf(long unscaledVal) {
         if ((unscaledVal >= 0) && (unscaledVal < BI_SCALED_BY_ZERO_LENGTH)) {
             return BI_SCALED_BY_ZERO[(int)unscaledVal];
@@ -477,7 +769,24 @@
         return new BigDecimal(unscaledVal,0);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} instance whose value is equal to {@code
+     * val}. The new decimal is constructed as if the {@code BigDecimal(String)}
+     * constructor is called with an argument which is equal to {@code
+     * Double.toString(val)}. For example, {@code valueOf("0.1")} is converted to
+     * (unscaled=1, scale=1), although the double {@code 0.1} cannot be
+     * represented exactly as a double value. In contrast to that, a new {@code
+     * BigDecimal(0.1)} instance has the value {@code
+     * 0.1000000000000000055511151231257827021181583404541015625} with an
+     * unscaled value {@code 1000000000000000055511151231257827021181583404541015625}
+     * and the scale {@code 55}.
+     *
+     * @param val
+     *            double value to be converted to a {@code BigDecimal}.
+     * @return {@code BigDecimal} instance with the value {@code val}.
+     * @throws NumberFormatException
+     *             if {@code val} is infinite or {@code val} is not a number
+     */
     public static BigDecimal valueOf(double val) {
         if (Double.isInfinite(val) || Double.isNaN(val)) {
             // math.03=Infinity or NaN
@@ -486,7 +795,17 @@
         return new BigDecimal(Double.toString(val));
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is {@code this + augend}.
+     * The scale of the result is the maximum of the scales of the two
+     * arguments.
+     *
+     * @param augend
+     *            value to be added to {@code this}.
+     * @return {@code this + augend}.
+     * @throws NullPointerException
+     *             if {@code augend == null}.
+     */
     public BigDecimal add(BigDecimal augend) {
         int diffScale = this.scale - augend.scale;
         // Fast return when some operand is zero
@@ -526,7 +845,18 @@
                 Multiplication.multiplyByTenPow(augend.getUnscaledValue(),diffScale)), thisValue.scale);
     }
     
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is {@code this + augend}.
+     * The result is rounded according to the passed context {@code mc}.
+     *
+     * @param augend
+     *            value to be added to {@code this}.
+     * @param mc
+     *            rounding mode and precision for the result of this operation.
+     * @return {@code this + augend}.
+     * @throws NullPointerException
+     *             if {@code augend == null} or {@code mc == null}.
+     */
     public BigDecimal add(BigDecimal augend, MathContext mc) {
         BigDecimal larger; // operand with the largest unscaled value
         BigDecimal smaller; // operand with the smallest unscaled value
@@ -568,7 +898,16 @@
         return larger.round(mc);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is {@code this - subtrahend}.
+     * The scale of the result is the maximum of the scales of the two arguments.
+     *
+     * @param subtrahend
+     *            value to be subtracted from {@code this}.
+     * @return {@code this - subtrahend}.
+     * @throws NullPointerException
+     *             if {@code subtrahend == null}.
+     */
     public BigDecimal subtract(BigDecimal subtrahend) {
         int diffScale = this.scale - subtrahend.scale;
         // Fast return when some operand is zero
@@ -610,7 +949,18 @@
         }
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is {@code this - subtrahend}.
+     * The result is rounded according to the passed context {@code mc}.
+     *
+     * @param subtrahend
+     *            value to be subtracted from {@code this}.
+     * @param mc
+     *            rounding mode and precision for the result of this operation.
+     * @return {@code this - subtrahend}.
+     * @throws NullPointerException
+     *             if {@code subtrahend == null} or {@code mc == null}.
+     */
     public BigDecimal subtract(BigDecimal subtrahend, MathContext mc) {
         long diffScale = subtrahend.scale - (long)this.scale;
         int thisSignum;
@@ -643,7 +993,17 @@
         return subtract(subtrahend).round(mc);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is {@code this *
+     * multiplicand}. The scale of the result is the sum of the scales of the
+     * two arguments.
+     *
+     * @param multiplicand
+     *            value to be multiplied with {@code this}.
+     * @return {@code this * multiplicand}.
+     * @throws NullPointerException
+     *             if {@code multiplicand == null}.
+     */
     public BigDecimal multiply(BigDecimal multiplicand) {
         long newScale = (long)this.scale + multiplicand.scale;
 
@@ -659,7 +1019,19 @@
                 multiplicand.getUnscaledValue()), toIntScale(newScale));
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is {@code this *
+     * multiplicand}. The result is rounded according to the passed context
+     * {@code mc}.
+     *
+     * @param multiplicand
+     *            value to be multiplied with {@code this}.
+     * @param mc
+     *            rounding mode and precision for the result of this operation.
+     * @return {@code this * multiplicand}.
+     * @throws NullPointerException
+     *             if {@code multiplicand == null} or {@code mc == null}.
+     */
     public BigDecimal multiply(BigDecimal multiplicand, MathContext mc) {
         BigDecimal result = multiply(multiplicand);
 
@@ -667,12 +1039,57 @@
         return result;
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is {@code this / divisor}.
+     * As scale of the result the parameter {@code scale} is used. If rounding
+     * is required to meet the specified scale, then the specified rounding mode
+     * {@code roundingMode} is applied.
+     *
+     * @param divisor
+     *            value by which {@code this} is divided.
+     * @param scale
+     *            the scale of the result returned.
+     * @param roundingMode
+     *            rounding mode to be used to round the result.
+     * @return {@code this / divisor} rounded according to the given rounding
+     *         mode.
+     * @throws NullPointerException
+     *             if {@code divisor == null}.
+     * @throws IllegalArgumentException
+     *             if {@code roundingMode} is not a valid rounding mode.
+     * @throws ArithmeticException
+     *             if {@code divisor == 0}.
+     * @throws ArithmeticException
+     *             if {@code roundingMode == ROUND_UNNECESSARY} and rounding is
+     *             necessary according to the given scale.
+     */
     public BigDecimal divide(BigDecimal divisor, int scale, int roundingMode) {
         return divide(divisor, scale, RoundingMode.valueOf(roundingMode));
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is {@code this / divisor}.
+     * As scale of the result the parameter {@code scale} is used. If rounding
+     * is required to meet the specified scale, then the specified rounding mode
+     * {@code roundingMode} is applied.
+     *
+     * @param divisor
+     *            value by which {@code this} is divided.
+     * @param scale
+     *            the scale of the result returned.
+     * @param roundingMode
+     *            rounding mode to be used to round the result.
+     * @return {@code this / divisor} rounded according to the given rounding
+     *         mode.
+     * @throws NullPointerException
+     *             if {@code divisor == null} or {@code roundingMode == null}.
+     * @throws ArithmeticException
+     *             if {@code divisor == 0}.
+     * @throws ArithmeticException
+     *             if {@code roundingMode == RoundingMode.UNNECESSAR}Y and
+     *             rounding is necessary according to the given scale and given
+     *             precision.
+     */
     public BigDecimal divide(BigDecimal divisor, int scale, RoundingMode roundingMode) {
         // Let be: this = [u1,s1]  and  divisor = [u2,s2]
         if (roundingMode == null) {
@@ -775,17 +1192,73 @@
         return valueOf(quotient, scale);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is {@code this / divisor}.
+     * The scale of the result is the scale of {@code this}. If rounding is
+     * required to meet the specified scale, then the specified rounding mode
+     * {@code roundingMode} is applied.
+     *
+     * @param divisor
+     *            value by which {@code this} is divided.
+     * @param roundingMode
+     *            rounding mode to be used to round the result.
+     * @return {@code this / divisor} rounded according to the given rounding
+     *         mode.
+     * @throws NullPointerException
+     *             if {@code divisor == null}.
+     * @throws IllegalArgumentException
+     *             if {@code roundingMode} is not a valid rounding mode.
+     * @throws ArithmeticException
+     *             if {@code divisor == 0}.
+     * @throws ArithmeticException
+     *             if {@code roundingMode == ROUND_UNNECESSARY} and rounding is
+     *             necessary according to the scale of this.
+     */
     public BigDecimal divide(BigDecimal divisor, int roundingMode) {
         return divide(divisor, scale, RoundingMode.valueOf(roundingMode));
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is {@code this / divisor}.
+     * The scale of the result is the scale of {@code this}. If rounding is
+     * required to meet the specified scale, then the specified rounding mode
+     * {@code roundingMode} is applied.
+     *
+     * @param divisor
+     *            value by which {@code this} is divided.
+     * @param roundingMode
+     *            rounding mode to be used to round the result.
+     * @return {@code this / divisor} rounded according to the given rounding
+     *         mode.
+     * @throws NullPointerException
+     *             if {@code divisor == null} or {@code roundingMode == null}.
+     * @throws ArithmeticException
+     *             if {@code divisor == 0}.
+     * @throws ArithmeticException
+     *             if {@code roundingMode == RoundingMode.UNNECESSARY} and
+     *             rounding is necessary according to the scale of this.
+     */
     public BigDecimal divide(BigDecimal divisor, RoundingMode roundingMode) {
         return divide(divisor, scale, roundingMode);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is {@code this / divisor}.
+     * The scale of the result is the difference of the scales of {@code this}
+     * and {@code divisor}. If the exact result requires more digits, then the
+     * scale is adjusted accordingly. For example, {@code 1/128 = 0.0078125}
+     * which has a scale of {@code 7} and precision {@code 5}.
+     *
+     * @param divisor
+     *            value by which {@code this} is divided.
+     * @return {@code this / divisor}.
+     * @throws NullPointerException
+     *             if {@code divisor == null}.
+     * @throws ArithmeticException
+     *             if {@code divisor == 0}.
+     * @throws ArithmeticException
+     *             if the result cannot be represented exactly.
+     */
     public BigDecimal divide(BigDecimal divisor) {
         BigInteger p = this.getUnscaledValue();
         BigInteger q = divisor.getUnscaledValue();
@@ -847,7 +1320,25 @@
         return new BigDecimal(p, newScale);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is {@code this / divisor}.
+     * The result is rounded according to the passed context {@code mc}. If the
+     * passed math context specifies precision {@code 0}, then this call is
+     * equivalent to {@code this.divide(divisor)}.
+     *
+     * @param divisor
+     *            value by which {@code this} is divided.
+     * @param mc
+     *            rounding mode and precision for the result of this operation.
+     * @return {@code this / divisor}.
+     * @throws NullPointerException
+     *             if {@code divisor == null} or {@code mc == null}.
+     * @throws ArithmeticException
+     *             if {@code divisor == 0}.
+     * @throws ArithmeticException
+     *             if {@code mc.getRoundingMode() == UNNECESSARY} and rounding
+     *             is necessary according {@code mc.getPrecision()}.
+     */
     public BigDecimal divide(BigDecimal divisor, MathContext mc) {
         /* Calculating how many zeros must be append to 'dividend'
          * to obtain a  quotient with at least 'mc.precision()' digits */
@@ -903,7 +1394,19 @@
         return new BigDecimal(integerQuot, toIntScale(newScale), mc);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is the integral part of
+     * {@code this / divisor}. The quotient is rounded down towards zero to the
+     * next integer. For example, {@code 0.5/0.2 = 2}.
+     *
+     * @param divisor
+     *            value by which {@code this} is divided.
+     * @return integral part of {@code this / divisor}.
+     * @throws NullPointerException
+     *             if {@code divisor == null}.
+     * @throws ArithmeticException
+     *             if {@code divisor == 0}.
+     */
     public BigDecimal divideToIntegralValue(BigDecimal divisor) {
         BigInteger integralValue; // the integer of result
         BigInteger powerOfTen; // some power of ten
@@ -955,7 +1458,27 @@
                 : new BigDecimal(integralValue, toIntScale(newScale)));
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is the integral part of
+     * {@code this / divisor}. The quotient is rounded down towards zero to the
+     * next integer. The rounding mode passed with the parameter {@code mc} is
+     * not considered. But if the precision of {@code mc > 0} and the integral
+     * part requires more digits, then an {@code ArithmeticException} is thrown.
+     *
+     * @param divisor
+     *            value by which {@code this} is divided.
+     * @param mc
+     *            math context which determines the maximal precision of the
+     *            result.
+     * @return integral part of {@code this / divisor}.
+     * @throws NullPointerException
+     *             if {@code divisor == null} or {@code mc == null}.
+     * @throws ArithmeticException
+     *             if {@code divisor == 0}.
+     * @throws ArithmeticException
+     *             if {@code mc.getPrecision() > 0} and the result requires more
+     *             digits to be represented.
+     */
     public BigDecimal divideToIntegralValue(BigDecimal divisor, MathContext mc) {
         int mcPrecision = mc.getPrecision();
         int diffPrecision = this.precision() - divisor.precision();
@@ -1047,17 +1570,67 @@
         return integralValue;
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is {@code this % divisor}.
+     * <p>
+     * The remainder is defined as {@code this -
+     * this.divideToIntegralValue(divisor) * divisor}.
+     *
+     * @param divisor
+     *            value by which {@code this} is divided.
+     * @return {@code this % divisor}.
+     * @throws NullPointerException
+     *             if {@code divisor == null}.
+     * @throws ArithmeticException
+     *             if {@code divisor == 0}.
+     */
     public BigDecimal remainder(BigDecimal divisor) {
         return divideAndRemainder(divisor)[1];
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is {@code this % divisor}.
+     * <p>
+     * The remainder is defined as {@code this -
+     * this.divideToIntegralValue(divisor) * divisor}.
+     * <p>
+     * The specified rounding mode {@code mc} is used for the division only.
+     *
+     * @param divisor
+     *            value by which {@code this} is divided.
+     * @param mc
+     *            rounding mode and precision to be used.
+     * @return {@code this % divisor}.
+     * @throws NullPointerException
+     *             if {@code divisor == null}.
+     * @throws ArithmeticException
+     *             if {@code divisor == 0}.
+     * @throws ArithmeticException
+     *             if {@code mc.getPrecision() > 0} and the result of {@code
+     *             this.divideToIntegralValue(divisor, mc)} requires more digits
+     *             to be represented.
+     */
     public BigDecimal remainder(BigDecimal divisor, MathContext mc) {
         return divideAndRemainder(divisor, mc)[1];
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a {@code BigDecimal} array which contains the integral part of
+     * {@code this / divisor} at index 0 and the remainder {@code this %
+     * divisor} at index 1. The quotient is rounded down towards zero to the
+     * next integer.
+     *
+     * @param divisor
+     *            value by which {@code this} is divided.
+     * @return {@code [this.divideToIntegralValue(divisor),
+     *         this.remainder(divisor)]}.
+     * @throws NullPointerException
+     *             if {@code divisor == null}.
+     * @throws ArithmeticException
+     *             if {@code divisor == 0}.
+     * @see #divideToIntegralValue
+     * @see #remainder
+     */
     public BigDecimal[] divideAndRemainder(BigDecimal divisor) {
         BigDecimal quotAndRem[] = new BigDecimal[2];
 
@@ -1066,7 +1639,28 @@
         return quotAndRem;
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a {@code BigDecimal} array which contains the integral part of
+     * {@code this / divisor} at index 0 and the remainder {@code this %
+     * divisor} at index 1. The quotient is rounded down towards zero to the
+     * next integer. The rounding mode passed with the parameter {@code mc} is
+     * not considered. But if the precision of {@code mc > 0} and the integral
+     * part requires more digits, then an {@code ArithmeticException} is thrown.
+     *
+     * @param divisor
+     *            value by which {@code this} is divided.
+     * @param mc
+     *            math context which determines the maximal precision of the
+     *            result.
+     * @return {@code [this.divideToIntegralValue(divisor),
+     *         this.remainder(divisor)]}.
+     * @throws NullPointerException
+     *             if {@code divisor == null}.
+     * @throws ArithmeticException
+     *             if {@code divisor == 0}.
+     * @see #divideToIntegralValue
+     * @see #remainder
+     */
     public BigDecimal[] divideAndRemainder(BigDecimal divisor, MathContext mc) {
         BigDecimal quotAndRem[] = new BigDecimal[2];
 
@@ -1075,7 +1669,21 @@
         return quotAndRem;
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is {@code this ^ n}. The
+     * scale of the result is {@code n} times the scales of {@code this}.
+     * <p>
+     * {@code x.pow(0)} returns {@code 1}, even if {@code x == 0}.
+     * <p>
+     * Implementation Note: The implementation is based on the ANSI standard
+     * X3.274-1996 algorithm.
+     *
+     * @param n
+     *            exponent to which {@code this} is raised.
+     * @return {@code this ^ n}.
+     * @throws ArithmeticException
+     *             if {@code n < 0} or {@code n > 999999999}.
+     */
     public BigDecimal pow(int n) {
         if (n == 0) {
             return ONE;
@@ -1091,7 +1699,21 @@
         : new BigDecimal(getUnscaledValue().pow(n), toIntScale(newScale)));
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is {@code this ^ n}. The
+     * result is rounded according to the passed context {@code mc}.
+     * <p>
+     * Implementation Note: The implementation is based on the ANSI standard
+     * X3.274-1996 algorithm.
+     *
+     * @param n
+     *            exponent to which {@code this} is raised.
+     * @param mc
+     *            rounding mode and precision for the result of this operation.
+     * @return {@code this ^ n}.
+     * @throws ArithmeticException
+     *             if {@code n < 0} or {@code n > 999999999}.
+     */
     public BigDecimal pow(int n, MathContext mc) {
         // The ANSI standard X3.274-1996 algorithm
         int m = Math.abs(n);
@@ -1134,17 +1756,35 @@
         return accum;
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is the absolute value of
+     * {@code this}. The scale of the result is the same as the scale of this.
+     *
+     * @return {@code abs(this)}
+     */
     public BigDecimal abs() {
         return ((signum() < 0) ? negate() : this);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is the absolute value of
+     * {@code this}. The result is rounded according to the passed context
+     * {@code mc}.
+     *
+     * @param mc
+     *            rounding mode and precision for the result of this operation.
+     * @return {@code abs(this)}
+     */
     public BigDecimal abs(MathContext mc) {
         return round(mc).abs();
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is the {@code -this}. The
+     * scale of the result is the same as the scale of this.
+     *
+     * @return {@code -this}
+     */
     public BigDecimal negate() {
         if(bitLength < 63 || (bitLength == 63 && smallValue!=Long.MIN_VALUE)) {
             return valueOf(-smallValue,scale);
@@ -1152,22 +1792,46 @@
         return new BigDecimal(getUnscaledValue().negate(), scale);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is the {@code -this}. The
+     * result is rounded according to the passed context {@code mc}.
+     *
+     * @param mc
+     *            rounding mode and precision for the result of this operation.
+     * @return {@code -this}
+     */
     public BigDecimal negate(MathContext mc) {
         return round(mc).negate();
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is {@code +this}. The scale
+     * of the result is the same as the scale of this.
+     *
+     * @return {@code this}
+     */
     public BigDecimal plus() {
         return this;
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is {@code +this}. The result
+     * is rounded according to the passed context {@code mc}.
+     *
+     * @param mc
+     *            rounding mode and precision for the result of this operation.
+     * @return {@code this}, rounded
+     */
     public BigDecimal plus(MathContext mc) {
         return round(mc);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns the sign of this {@code BigDecimal}.
+     *
+     * @return {@code -1} if {@code this < 0},
+     *         {@code 0} if {@code this == 0},
+     *         {@code 1} if {@code this > 0}.     */
     public int signum() {
         if( bitLength < 64) {
             return Long.signum( this.smallValue );
@@ -1180,12 +1844,26 @@
         return bitLength == 0 && this.smallValue != -1;
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns the scale of this {@code BigDecimal}. The scale is the number of
+     * digits behind the decimal point. The value of this {@code BigDecimal} is
+     * the unsignedValue * 10^(-scale). If the scale is negative, then this
+     * {@code BigDecimal} represents a big integer.
+     *
+     * @return the scale of this {@code BigDecimal}.
+     */
     public int scale() {
         return scale;
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns the precision of this {@code BigDecimal}. The precision is the
+     * number of decimal digits used to represent this decimal. It is equivalent
+     * to the number of digits of the unscaled value. The precision of {@code 0}
+     * is {@code 1} (independent of the scale).
+     *
+     * @return the precision of this {@code BigDecimal}.
+     */
     public int precision() {
         // Checking if the precision already was calculated
         if (precision > 0) {
@@ -1216,12 +1894,35 @@
         return precision;
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns the unscaled value (mantissa) of this {@code BigDecimal} instance
+     * as a {@code BigInteger}. The unscaled value can be computed as {@code
+     * this} 10^(scale).
+     *
+     * @return unscaled value (this * 10^(scale)).
+     */
     public BigInteger unscaledValue() {
         return getUnscaledValue();
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is {@code this}, rounded
+     * according to the passed context {@code mc}.
+     * <p>
+     * If {@code mc.precision = 0}, then no rounding is performed.
+     * <p>
+     * If {@code mc.precision > 0} and {@code mc.roundingMode == UNNECESSARY},
+     * then an {@code ArithmeticException} is thrown if the result cannot be
+     * represented exactly within the given precision.
+     *
+     * @param mc
+     *            rounding mode and precision for the result of this operation.
+     * @return {@code this} rounded according to the passed context.
+     * @throws ArithmeticException
+     *             if {@code mc.precision > 0} and {@code mc.roundingMode ==
+     *             UNNECESSARY} and this cannot be represented within the given
+     *             precision.
+     */
     public BigDecimal round(MathContext mc) {
         BigDecimal thisBD = new BigDecimal(getUnscaledValue(), scale);
 
@@ -1229,7 +1930,28 @@
         return thisBD;
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} instance with the specified scale.
+     * <p>
+     * If the new scale is greater than the old scale, then additional zeros are
+     * added to the unscaled value. In this case no rounding is necessary.
+     * <p>
+     * If the new scale is smaller than the old scale, then trailing digits are
+     * removed. If these trailing digits are not zero, then the remaining
+     * unscaled value has to be rounded. For this rounding operation the
+     * specified rounding mode is used.
+     *
+     * @param newScale
+     *            scale of the result returned.
+     * @param roundingMode
+     *            rounding mode to be used to round the result.
+     * @return a new {@code BigDecimal} instance with the specified scale.
+     * @throws NullPointerException
+     *             if {@code roundingMode == null}.
+     * @throws ArithmeticException
+     *             if {@code roundingMode == ROUND_UNNECESSARY} and rounding is
+     *             necessary according to the given scale.
+     */
     public BigDecimal setScale(int newScale, RoundingMode roundingMode) {
         if (roundingMode == null) {
             throw new NullPointerException();
@@ -1255,17 +1977,68 @@
         return divideBigIntegers(this.getUnscaledValue(),Multiplication.powerOf10(-diffScale),newScale,roundingMode);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} instance with the specified scale.
+     * <p>
+     * If the new scale is greater than the old scale, then additional zeros are
+     * added to the unscaled value. In this case no rounding is necessary.
+     * <p>
+     * If the new scale is smaller than the old scale, then trailing digits are
+     * removed. If these trailing digits are not zero, then the remaining
+     * unscaled value has to be rounded. For this rounding operation the
+     * specified rounding mode is used.
+     *
+     * @param newScale
+     *            scale of the result returned.
+     * @param roundingMode
+     *            rounding mode to be used to round the result.
+     * @return a new {@code BigDecimal} instance with the specified scale.
+     * @throws IllegalArgumentException
+     *             if {@code roundingMode} is not a valid rounding mode.
+     * @throws ArithmeticException
+     *             if {@code roundingMode == ROUND_UNNECESSARY} and rounding is
+     *             necessary according to the given scale.
+     */
     public BigDecimal setScale(int newScale, int roundingMode) {
         return setScale(newScale, RoundingMode.valueOf(roundingMode));
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} instance with the specified scale. If
+     * the new scale is greater than the old scale, then additional zeros are
+     * added to the unscaled value. If the new scale is smaller than the old
+     * scale, then trailing zeros are removed. If the trailing digits are not
+     * zeros then an ArithmeticException is thrown.
+     * <p>
+     * If no exception is thrown, then the following equation holds: {@code
+     * x.setScale(s).compareTo(x) == 0}.
+     *
+     * @param newScale
+     *            scale of the result returned.
+     * @return a new {@code BigDecimal} instance with the specified scale.
+     * @throws ArithmeticException
+     *             if rounding would be necessary.
+     */
     public BigDecimal setScale(int newScale) {
         return setScale(newScale, RoundingMode.UNNECESSARY);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} instance where the decimal point has
+     * been moved {@code n} places to the left. If {@code n < 0} then the
+     * decimal point is moved {@code -n} places to the right.
+     * <p>
+     * The result is obtained by changing its scale. If the scale of the result
+     * becomes negative, then its precision is increased such that the scale is
+     * zero.
+     * <p>
+     * Note, that {@code movePointLeft(0)} returns a result which is
+     * mathematically equivalent, but which has {@code scale >= 0}.
+     *
+     * @param n
+     *            number of placed the decimal point has to be moved.
+     * @return {@code this * 10^(-n}).
+     */
     public BigDecimal movePointLeft(int n) {
         return movePoint(scale + (long)n);
     }
@@ -1289,12 +2062,38 @@
         return new BigDecimal(Multiplication.multiplyByTenPow(getUnscaledValue(),(int)-newScale), 0);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} instance where the decimal point has
+     * been moved {@code n} places to the right. If {@code n < 0} then the
+     * decimal point is moved {@code -n} places to the left.
+     * <p>
+     * The result is obtained by changing its scale. If the scale of the result
+     * becomes negative, then its precision is increased such that the scale is
+     * zero.
+     * <p>
+     * Note, that {@code movePointRight(0)} returns a result which is
+     * mathematically equivalent, but which has scale >= 0.
+     *
+     * @param n
+     *            number of placed the decimal point has to be moved.
+     * @return {@code this * 10^n}.
+     */
     public BigDecimal movePointRight(int n) {
         return movePoint(scale - (long)n);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} whose value is {@code this} 10^{@code n}.
+     * The scale of the result is {@code this.scale()} - {@code n}.
+     * The precision of the result is the precision of {@code this}.
+     * <p>
+     * This method has the same effect as {@link #movePointRight}, except that
+     * the precision is not changed.
+     *
+     * @param n
+     *            number of places the decimal point has to be moved.
+     * @return {@code this * 10^n}
+     */
     public BigDecimal scaleByPowerOfTen(int n) {
         long newScale = scale - (long)n;
         if(bitLength < 64) {
@@ -1307,7 +2106,15 @@
         return new BigDecimal(getUnscaledValue(), toIntScale(newScale));
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a new {@code BigDecimal} instance with the same value as {@code
+     * this} but with a unscaled value where the trailing zeros have been
+     * removed. If the unscaled value of {@code this} has n trailing zeros, then
+     * the scale and the precision of the result has been reduced by n.
+     *
+     * @return a new {@code BigDecimal} instance equivalent to this where the
+     *         trailing zeros of the unscaled value have been removed.
+     */
     public BigDecimal stripTrailingZeros() {
         int i = 1; // 1 <= i <= 18
         int lastPow = TEN_POW.length - 1;
@@ -1344,7 +2151,22 @@
         return new BigDecimal(strippedBI, toIntScale(newScale));
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Compares this {@code BigDecimal} with {@code val}. Returns one of the
+     * three values {@code 1}, {@code 0}, or {@code -1}. The method behaves as
+     * if {@code this.subtract(val)} is computed. If this difference is > 0 then
+     * 1 is returned, if the difference is < 0 then -1 is returned, and if the
+     * difference is 0 then 0 is returned. This means, that if two decimal
+     * instances are compared which are equal in value but differ in scale, then
+     * these two instances are considered as equal.
+     *
+     * @param val
+     *            value to be compared with {@code this}.
+     * @return {@code 1} if {@code this > val}, {@code -1} if {@code this < val},
+     *         {@code 0} if {@code this == val}.
+     * @throws NullPointerException
+     *             if {@code val == null}.
+     */
     public int compareTo(BigDecimal val) {
         int thisSign = signum();
         int valueSign = val.signum();
@@ -1377,50 +2199,90 @@
         }
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns {@code true} if {@code x} is a {@code BigDecimal} instance and if
+     * this instance is equal to this big decimal. Two big decimals are equal if
+     * their unscaled value and their scale is equal. For example, 1.0
+     * (10*10^(-1)) is not equal to 1.00 (100*10^(-2)). Similarly, zero
+     * instances are not equal if their scale differs.
+     *
+     * @param x
+     *            object to be compared with {@code this}.
+     * @return true if {@code x} is a {@code BigDecimal} and {@code this == x}.
+     */
     @Override
-    public boolean equals(Object x) {    	
-    	if (this == x) {
-    		return true;
-    	}
-    	if (x instanceof BigDecimal) {
-    	    BigDecimal x1 = (BigDecimal) x;    	    
-    	    return x1.scale == scale                   
+    public boolean equals(Object x) {
+        if (this == x) {
+            return true;
+        }
+        if (x instanceof BigDecimal) {
+            BigDecimal x1 = (BigDecimal) x;
+            return x1.scale == scale
                    && (bitLength < 64 ? (x1.smallValue == smallValue)
                     : intVal.equals(x1.intVal));
-                	    
-    	     
-    	} 
-    	return false;       
+
+
+        }
+        return false;
     }   
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns the minimum of this {@code BigDecimal} and {@code val}.
+     *
+     * @param val
+     *            value to be used to compute the minimum with this.
+     * @return {@code min(this, val}.
+     * @throws NullPointerException
+     *             if {@code val == null}.
+     */
     public BigDecimal min(BigDecimal val) {
         return ((compareTo(val) <= 0) ? this : val);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns the maximum of this {@code BigDecimal} and {@code val}.
+     *
+     * @param val
+     *            value to be used to compute the maximum with this.
+     * @return {@code max(this, val}.
+     * @throws NullPointerException
+     *             if {@code val == null}.
+     */
     public BigDecimal max(BigDecimal val) {
         return ((compareTo(val) >= 0) ? this : val);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a hash code for this {@code BigDecimal}.
+     *
+     * @return hash code for {@code this}.
+     */
     @Override
     public int hashCode() {        
-    	if (hashCode != 0) {
-    		return hashCode;
-    	}
-    	if (bitLength < 64) {
-    		hashCode = (int)(smallValue & 0xffffffff);
-    		hashCode = 33 * hashCode +  (int)((smallValue >> 32) & 0xffffffff);
-    		hashCode = 17 * hashCode + scale;   		
-    		return hashCode;
-    	}
-    	hashCode = 17 * intVal.hashCode() + scale;    	
-    	return hashCode;    	
+        if (hashCode != 0) {
+            return hashCode;
+        }
+        if (bitLength < 64) {
+            hashCode = (int)(smallValue & 0xffffffff);
+            hashCode = 33 * hashCode +  (int)((smallValue >> 32) & 0xffffffff);
+            hashCode = 17 * hashCode + scale;
+            return hashCode;
+        }
+        hashCode = 17 * intVal.hashCode() + scale;
+        return hashCode;
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a canonical string representation of this {@code BigDecimal}. If
+     * necessary, scientific notation is used. This representation always prints
+     * all significant digits of this value.
+     * <p>
+     * If the scale is negative or if {@code scale - precision >= 6} then
+     * scientific notation is used.
+     *
+     * @return a string representation of {@code this} in scientific notation if
+     *         necessary.
+     */
     @Override
     public String toString() {
         if (toStringImage != null) {
@@ -1462,7 +2324,18 @@
         return toStringImage;
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a string representation of this {@code BigDecimal}. This
+     * representation always prints all significant digits of this value.
+     * <p>
+     * If the scale is negative or if {@code scale - precision >= 6} then
+     * engineering notation is used. Engineering notation is similar to the
+     * scientific notation except that the exponent is made to be a multiple of
+     * 3 such that the integer part is >= 1 and < 1000.
+     *
+     * @return a string representation of {@code this} in engineering notation
+     *         if necessary.
+     */
     public String toEngineeringString() {
         String intString = getUnscaledValue().toString();
         if (scale == 0) {
@@ -1517,7 +2390,21 @@
         return result.toString();
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns a string representation of this {@code BigDecimal}. No scientific
+     * notation is used. This methods adds zeros where necessary.
+     * <p>
+     * If this string representation is used to create a new instance, this
+     * instance is generally not identical to {@code this} as the precision
+     * changes.
+     * <p>
+     * {@code x.equals(new BigDecimal(x.toPlainString())} usually returns
+     * {@code false}.
+     * <p>
+     * {@code x.compareTo(new BigDecimal(x.toPlainString())} returns {@code 0}.
+     *
+     * @return a string representation of {@code this} without exponent part.
+     */
     public String toPlainString() {
         String intStr = getUnscaledValue().toString();
         if ((scale == 0) || ((isZero()) && (scale < 0))) {
@@ -1559,7 +2446,12 @@
         return result.toString();
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns this {@code BigDecimal} as a big integer instance. A fractional
+     * part is discarded.
+     *
+     * @return this {@code BigDecimal} as a big integer instance.
+     */
     public BigInteger toBigInteger() {
         if ((scale == 0) || (isZero())) {
             return getUnscaledValue();
@@ -1570,7 +2462,15 @@
         }
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns this {@code BigDecimal} as a big integer instance if it has no
+     * fractional part. If this {@code BigDecimal} has a fractional part, i.e.
+     * if rounding would be necessary, an {@code ArithmeticException} is thrown.
+     *
+     * @return this {@code BigDecimal} as a big integer value.
+     * @throws ArithmeticException
+     *             if rounding is necessary.
+     */
     public BigInteger toBigIntegerExact() {
         if ((scale == 0) || (isZero())) {
             return getUnscaledValue();
@@ -1593,7 +2493,13 @@
         }
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns this {@code BigDecimal} as an long value. Any fractional part is
+     * discarded. If the integral part of {@code this} is too big to be
+     * represented as an long, then {@code this} % 2^64 is returned.
+     *
+     * @return this {@code BigDecimal} as a long value.
+     */
     @Override
     public long longValue() {
         /* If scale <= -64 there are at least 64 trailing bits zero in 10^(-scale).
@@ -1603,12 +2509,26 @@
                 : toBigInteger().longValue());
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns this {@code BigDecimal} as a long value if it has no fractional
+     * part and if its value fits to the int range ([-2^{63}..2^{63}-1]). If
+     * these conditions are not met, an {@code ArithmeticException} is thrown.
+     *
+     * @return this {@code BigDecimal} as a long value.
+     * @throws ArithmeticException
+     *             if rounding is necessary or the number doesn't fit in a long.
+     */
     public long longValueExact() {
         return valueExact(64);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns this {@code BigDecimal} as an int value. Any fractional part is
+     * discarded. If the integral part of {@code this} is too big to be
+     * represented as an int, then {@code this} % 2^32 is returned.
+     *
+     * @return this {@code BigDecimal} as a int value.
+     */
     @Override
     public int intValue() {
         /* If scale <= -32 there are at least 32 trailing bits zero in 10^(-scale).
@@ -1618,22 +2538,64 @@
                 : toBigInteger().intValue());
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns this {@code BigDecimal} as a int value if it has no fractional
+     * part and if its value fits to the int range ([-2^{31}..2^{31}-1]). If
+     * these conditions are not met, an {@code ArithmeticException} is thrown.
+     *
+     * @return this {@code BigDecimal} as a int value.
+     * @throws ArithmeticException
+     *             if rounding is necessary or the number doesn't fit in a int.
+     */
     public int intValueExact() {
         return (int)valueExact(32);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns this {@code BigDecimal} as a short value if it has no fractional
+     * part and if its value fits to the short range ([-2^{15}..2^{15}-1]). If
+     * these conditions are not met, an {@code ArithmeticException} is thrown.
+     *
+     * @return this {@code BigDecimal} as a short value.
+     * @throws ArithmeticException
+     *             if rounding is necessary of the number doesn't fit in a
+     *             short.
+     */
     public short shortValueExact() {
         return (short)valueExact(16);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns this {@code BigDecimal} as a byte value if it has no fractional
+     * part and if its value fits to the byte range ([-128..127]). If these
+     * conditions are not met, an {@code ArithmeticException} is thrown.
+     *
+     * @return this {@code BigDecimal} as a byte value.
+     * @throws ArithmeticException
+     *             if rounding is necessary or the number doesn't fit in a byte.
+     */
     public byte byteValueExact() {
         return (byte)valueExact(8);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns this {@code BigDecimal} as a float value. If {@code this} is too
+     * big to be represented as an float, then {@code Float.POSITIVE_INFINITY}
+     * or {@code Float.NEGATIVE_INFINITY} is returned.
+     * <p>
+     * Note, that if the unscaled value has more than 24 significant digits,
+     * then this decimal cannot be represented exactly in a float variable. In
+     * this case the result is rounded.
+     * <p>
+     * For example, if the instance {@code x1 = new BigDecimal("0.1")} cannot be
+     * represented exactly as a float, and thus {@code x1.equals(new
+     * BigDecimal(x1.folatValue())} returns {@code false} for this case.
+     * <p>
+     * Similarly, if the instance {@code new BigDecimal(16777217)} is converted
+     * to a float, the result is {@code 1.6777216E}7.
+     *
+     * @return this {@code BigDecimal} as a float value.
+     */
     @Override
     public float floatValue() {
         /* A similar code like in doubleValue() could be repeated here,
@@ -1652,7 +2614,25 @@
         return floatResult;
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns this {@code BigDecimal} as a double value. If {@code this} is too
+     * big to be represented as an float, then {@code Double.POSITIVE_INFINITY}
+     * or {@code Double.NEGATIVE_INFINITY} is returned.
+     * <p>
+     * Note, that if the unscaled value has more than 53 significant digits,
+     * then this decimal cannot be represented exactly in a double variable. In
+     * this case the result is rounded.
+     * <p>
+     * For example, if the instance {@code x1 = new BigDecimal("0.1")} cannot be
+     * represented exactly as a double, and thus {@code x1.equals(new
+     * BigDecimal(x1.doubleValue())} returns {@code false} for this case.
+     * <p>
+     * Similarly, if the instance {@code new BigDecimal(9007199254740993L)} is
+     * converted to a double, the result is {@code 9.007199254740992E15}.
+     * <p>
+     *
+     * @return this {@code BigDecimal} as a double value.
+     */
     @Override
     public double doubleValue() {
         int sign = signum();
@@ -1754,7 +2734,21 @@
         return Double.longBitsToDouble(bits);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns the unit in the last place (ULP) of this {@code BigDecimal}
+     * instance. An ULP is the distance to the nearest big decimal with the same
+     * precision.
+     * <p>
+     * The amount of a rounding error in the evaluation of a floating-point
+     * operation is often expressed in ULPs. An error of 1 ULP is often seen as
+     * a tolerable error.
+     * <p>
+     * For class {@code BigDecimal}, the ULP of a number is simply 10^(-scale).
+     * <p>
+     * For example, {@code new BigDecimal(0.1).ulp()} returns {@code 1E-55}.
+     *
+     * @return unit in the last place (ULP) of this {@code BigDecimal} instance.
+     */
     public BigDecimal ulp() {
         return valueOf(1, scale);
     }
@@ -1762,15 +2756,18 @@
     /* Private Methods */
 
     /**
-     * It does all rounding work of the public method <code>round(MathContext)</code>, 
-     * performing an inplace rounding without creating a new object.
-     * @param mc the <code>MathContext</code> for perform the rounding.
-     * @see #round(MathContext).
+     * It does all rounding work of the public method
+     * {@code round(MathContext)}, performing an inplace rounding
+     * without creating a new object.
+     *
+     * @param mc
+     *            the {@code MathContext} for perform the rounding.
+     * @see #round(MathContext)
      */
     private void inplaceRound(MathContext mc) {
-    	int mcPrecision = mc.getPrecision();
+        int mcPrecision = mc.getPrecision();
         if (aproxPrecision() - mcPrecision <= 0 || mcPrecision == 0) {
-        	return;
+            return;
         }
         int discardedPrecision = precision() - mcPrecision;
         // If no rounding is necessary it returns immediately
@@ -1816,11 +2813,14 @@
         return value1 > value2 ? 1 : (value1 < value2 ? -1 : 0);
     }
     /**
-     * This method implements an efficient rounding for numbers which unscaled 
-     * value fits in the type <code>long</code>.
-     * @param mc the context to use.
-     * @param discardedPrecision the number of decimal digits that are discarded.
-     * @see #round(MathContext).
+     * This method implements an efficient rounding for numbers which unscaled
+     * value fits in the type {@code long}.
+     *
+     * @param mc
+     *            the context to use
+     * @param discardedPrecision
+     *            the number of decimal digits that are discarded
+     * @see #round(MathContext)
      */
     private void smallRound(MathContext mc, int discardedPrecision) {
         long sizeOfFraction = LONG_TEN_POW[discardedPrecision];
@@ -1853,11 +2853,17 @@
     }
 
     /**
-     * Return an increment that can be -1,0 or 1, depending of <code>roundingMode</code>.
-     * @param parityBit can be 0 or 1, it's only used in the case <code>HALF_EVEN</code>.  
-     * @param fraction the mantisa to be analyzed.
-     * @param roundingMode the type of rounding.
-     * @return the carry propagated after rounding.
+     * Return an increment that can be -1,0 or 1, depending of
+     * {@code roundingMode}.
+     *
+     * @param parityBit
+     *            can be 0 or 1, it's only used in the case
+     *            {@code HALF_EVEN}
+     * @param fraction
+     *            the mantisa to be analyzed
+     * @param roundingMode
+     *            the type of rounding
+     * @return the carry propagated after rounding
      */
     private static int roundingBehavior(int parityBit, int fraction, RoundingMode roundingMode) {
         int increment = 0; // the carry after rounding
@@ -1900,18 +2906,19 @@
     }
 
     /**
-     * If <code>intVal</code> has a fractional part throws an exception,
-     * otherwise it counts the number of bits of value and checks if it's out 
-     * of the range of the primitive type. If the number fits in the primitive
-     * type returns this number as <code>long</code>, otherwise throws an
-     * exception. 
-     *
-     * @param bitLengthOfType number of bits of the type whose value will be 
-     *         calculated exactly.
-     * @return the exact value of the integer part of <code>BigDecimal</code>
-     *         when is possible.
-     * @throws <code>ArithmeticException</code> when rounding is necessary or
-     *      the number don't fit in the primitive type.        
+     * If {@code intVal} has a fractional part throws an exception,
+     * otherwise it counts the number of bits of value and checks if it's out of
+     * the range of the primitive type. If the number fits in the primitive type
+     * returns this number as {@code long}, otherwise throws an
+     * exception.
+     *
+     * @param bitLengthOfType
+     *            number of bits of the type whose value will be calculated
+     *            exactly
+     * @return the exact value of the integer part of {@code BigDecimal}
+     *         when is possible
+     * @throws ArithmeticException when rounding is necessary or the
+     *             number don't fit in the primitive type
      */
     private long valueExact(int bitLengthOfType) {
         BigInteger bigInteger = toBigIntegerExact();
@@ -1926,10 +2933,11 @@
 
     /**
      * If the precision already was calculated it returns that value, otherwise
-     * it calculates a very good approximation efficiently . Note that this 
-     * value will be <code>precision()</code> or <code>precision()-1</code>
+     * it calculates a very good approximation efficiently . Note that this
+     * value will be {@code precision()} or {@code precision()-1}
      * in the worst case.
-     * @return an approximation of <code>precision()</code> value
+     *
+     * @return an approximation of {@code precision()} value
      */
     private int aproxPrecision() {
         return ((precision > 0)
@@ -1938,14 +2946,16 @@
     }
 
     /**
-     * It tests if a scale of type <code>long</code> fits in 32 bits. 
-     * It returns the same scale being casted to <code>int</code> type when 
-     * is possible, otherwise throws an exception.
-     * @param longScale a 64 bit scale.
-     * @return a 32 bit scale when is possible.
-     * @throws <code>ArithmeticException</code> when <code>scale</code> 
-     *      doesn't fit in <code>int</code> type. 
-     * @see #scale     
+     * It tests if a scale of type {@code long} fits in 32 bits. It
+     * returns the same scale being casted to {@code int} type when is
+     * possible, otherwise throws an exception.
+     *
+     * @param longScale
+     *            a 64 bit scale
+     * @return a 32 bit scale when is possible
+     * @throws ArithmeticException when {@code scale} doesn't
+     *             fit in {@code int} type
+     * @see #scale
      */
     private static int toIntScale(long longScale) {
         if (longScale < Integer.MIN_VALUE) {
@@ -1960,14 +2970,16 @@
     }
 
     /**
-     * It returns the value 0 with the most approximated scale of type 
-     * <code>int</code>. if <code>longScale > Integer.MAX_VALUE</code> 
-     * the scale will be <code>Integer.MAX_VALUE</code>; if 
-     * <code>longScale < Integer.MIN_VALUE</code> the scale will be
-     * <code>Integer.MIN_VALUE</code>; otherwise <code>longScale</code> is 
-     * casted to the type <code>int</code>. 
-     * @param longScale the scale to which the value 0 will be scaled.
-     * @return the value 0 scaled by the closer scale of type <code>int</code>.
+     * It returns the value 0 with the most approximated scale of type
+     * {@code int}. if {@code longScale > Integer.MAX_VALUE} the
+     * scale will be {@code Integer.MAX_VALUE}; if
+     * {@code longScale < Integer.MIN_VALUE} the scale will be
+     * {@code Integer.MIN_VALUE}; otherwise {@code longScale} is
+     * casted to the type {@code int}.
+     *
+     * @param longScale
+     *            the scale to which the value 0 will be scaled.
+     * @return the value 0 scaled by the closer scale of type {@code int}.
      * @see #scale
      */
     private static BigDecimal zeroScaledBy(long longScale) {
@@ -1980,7 +2992,11 @@
         return new BigDecimal( 0, Integer.MIN_VALUE);
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Assignes all transient fields upon deserialization of a
+     * {@code BigDecimal} instance (bitLength and smallValue). The transient
+     * field precision is assigned lazily.
+     */
     private void readObject(ObjectInputStream in) throws IOException,
             ClassNotFoundException {
         in.defaultReadObject();
@@ -1991,6 +3007,10 @@
         }
     }
 
+    /**
+     * Prepares this {@code BigDecimal} for serialization, i.e. the
+     * non-transient field {@code intVal} is assigned.
+     */
     private void writeObject(ObjectOutputStream out) throws IOException {
         getUnscaledValue();
         out.defaultWriteObject();



Mime
View raw message