Code review request for 6560935: BigInteger.modPow() throws ArithmeticException for negative exponent

[Joseph D. Darcy]

Hello.

Please review this small doc clarification; modPow is not defined for 
negative exponents unless the BigInteger being operated on is relatively 
prime to the modulus.  There are a few stylistic javadoc cleanups in the 
patch below too.

Webrev:
http://cr.openjdk.java.net/~darcy/6560935.0/

Thanks,

-Joe

--- old/src/share/classes/java/math/BigInteger.java    2009-10-20 
14:40:35.000000000 -0700
+++ new/src/share/classes/java/math/BigInteger.java    2009-10-20 
14:40:35.000000000 -0700
@@ -478,7 +478,7 @@

    /**
     * Constructs a randomly generated BigInteger, uniformly 
distributed over
-     * the range {...@code 0} to (2<sup>{...@code numBits}</sup> - 1), 
inclusive.
+     * the range 0 to (2<sup>{...@code numBits}</sup> - 1), inclusive.
     * The uniformity of the distribution assumes that a fair source of 
random
     * bits is provided in {...@code rnd}.  Note that this constructor always
     * constructs a non-negative BigInteger.
@@ -1332,7 +1332,7 @@
     *
     * @param  val value by which this BigInteger is to be divided.
     * @return {...@code this / val}
-     * @throws ArithmeticException {...@code val==0}
+     * @throws ArithmeticException if {...@code val} is zero.
     */
    public BigInteger divide(BigInteger val) {
        MutableBigInteger q = new MutableBigInteger(),
@@ -1352,7 +1352,7 @@
     * @return an array of two BigIntegers: the quotient {...@code (this / 
val)}
     *         is the initial element, and the remainder {...@code (this % 
val)}
     *         is the final element.
-     * @throws ArithmeticException {...@code val==0}
+     * @throws ArithmeticException if {...@code val} is zero.
     */
    public BigInteger[] divideAndRemainder(BigInteger val) {
        BigInteger[] result = new BigInteger[2];
@@ -1371,7 +1371,7 @@
     * @param  val value by which this BigInteger is to be divided, and the
     *         remainder computed.
     * @return {...@code this % val}
-     * @throws ArithmeticException {...@code val==0}
+     * @throws ArithmeticException if {...@code val} is zero.
     */
    public BigInteger remainder(BigInteger val) {
        MutableBigInteger q = new MutableBigInteger(),
@@ -1547,7 +1547,7 @@
     *
     * @param  m the modulus.
     * @return {...@code this mod m}
-     * @throws ArithmeticException {...@code m <= 0}
+     * @throws ArithmeticException {...@code m} &le; 0
     * @see    #remainder
     */
    public BigInteger mod(BigInteger m) {
@@ -1566,7 +1566,9 @@
     * @param  exponent the exponent.
     * @param  m the modulus.
     * @return <tt>this<sup>exponent</sup> mod m</tt>
-     * @throws ArithmeticException {...@code m <= 0}
+     * @throws ArithmeticException {...@code m} &le; 0 or the exponent is
+     *         negative and this BigInteger is not <i>relatively
+     *         prime</i> to m.
     * @see    #modInverse
     */
    public BigInteger modPow(BigInteger exponent, BigInteger m) {
@@ -2015,7 +2017,7 @@
     *
     * @param  m the modulus.
     * @return {...@code this}<sup>-1</sup> {...@code mod m}.
-     * @throws ArithmeticException {...@code  m <= 0}, or this BigInteger
+     * @throws ArithmeticException {...@code  m} &le; 0, or this BigInteger
     *         has no multiplicative inverse mod m (that is, this 
BigInteger
     *         is not <i>relatively prime</i> to m).
     */
@@ -2449,7 +2451,7 @@
    /**
     * Returns {...@code true} if this BigInteger is probably prime,
     * {...@code false} if it's definitely composite.  If
-     * {...@code certainty} is {...@code  <= 0}, {...@code true} is
+     * {...@code certainty} is &le; 0, {...@code true} is
     * returned.
     *
     * @param  certainty a measure of the uncertainty that the caller is