Index: modules/math/src/main/java/java/math/BitLevel.java =================================================================== --- modules/math/src/main/java/java/math/BitLevel.java (revision 801248) +++ modules/math/src/main/java/java/math/BitLevel.java Wed Aug 05 12:53:46 PDT 2009 @@ -165,14 +165,26 @@ } } + /** + * Shifts the source digits left one bit, creating a value whose magnitude + * is doubled. + * + * @param result an array of digits that will hold the computed result when + * this method returns. The size of this array is {@code srcLen + 1}, + * and the format is the same as {@link BigInteger#digits}. + * @param source the array of digits to shift left, in the same format as + * {@link BigInteger#digits}. + * @param srcLen the length of {@code source}; may be less than {@code + * source.length} + */ static void shiftLeftOneBit(int result[], int source[], int srcLen) { int carry = 0; - for(int i = 0; i < srcLen; i++) { + for (int i = 0; i < srcLen; i++) { int val = source[i]; result[i] = (val << 1) | carry; carry = val >>> 31; } - if(carry != 0) { + if (carry != 0) { result[srcLen] = carry; } } Index: modules/math/src/main/java/java/math/BigInteger.java =================================================================== --- modules/math/src/main/java/java/math/BigInteger.java (revision 801248) +++ modules/math/src/main/java/java/math/BigInteger.java Wed Aug 05 12:50:35 PDT 2009 @@ -47,7 +47,17 @@ /* Fields used for the internal representation. */ - /** The magnitude of this in the little-endian representation. */ + /** + * The magnitude of this big integer. This array holds unsigned little + * endian digits. For example: + * {@code 13} is represented as [ 13 ] + * {@code -13} is represented as [ 13 ] + * {@code 2^32 + 13} is represented as [ 13, 1 ] + * {@code 2^64 + 13} is represented as [ 13, 0, 1 ] + * {@code 2^31} is represented as [ Integer.MIN_VALUE ] + * The magnitude array may be longer than strictly necessary, which results + * in additional trailing zeros. + */ transient int digits[]; /** The length of this in measured in ints. Can be less than digits.length(). */