Change documentation of modInverse to not specify error thrown.

sdk/lib/core/int.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.core;
 
 /**
  * An arbitrarily large integer.
  *
  * **Note:** When compiling to JavaScript, integers are
@@ skipping 70 matching lines @@
   /**
    * Shift the bits of this integer to the left by [shiftAmount].
    *
    * Shifting to the left makes the number larger, effectively multiplying
    * the number by `pow(2, shiftIndex)`.
    *
    * There is no limit on the size of the result. It may be relevant to
    * limit intermediate values by using the "and" operator with a suitable
    * mask.
    *
    * It is an error of [shiftAmount] is negative.

[regis, 2015/06/24 18:29:54]

of -> if

    */
   int operator <<(int shiftAmount);
 
   /**
    * Shift the bits of this integer to the right by [shiftAmount].
    *
    * Shifting to the right makes the number smaller and drops the least
    * significant bits, effectively doing an integer division by
    *`pow(2, shiftIndex)`.
    *
    * It is an error of [shiftAmount] is negative.

[regis, 2015/06/24 18:29:54]

of -> if

    */
   int operator >>(int shiftAmount);
 
   /**
    * Returns this integer to the power of [exponent] modulo [modulus].
    *
    * The [exponent] must be non-negative and [modulus] must be
    * positive.
    */
   int modPow(int exponent, int modulus);
 
   /**
    * Returns the modular multiplicative inverse of this integer
    * modulo [modulus].
    *
    * The [modulus] must be positive.
-   * Throws a RangeError if no modular inverse exists.
+   * Throws if no modular inverse exists.

[regis, 2015/06/24 18:29:54]

For consistency, "It is an error if ..." would have been better.

[Lasse Reichstein Nielsen, 2015/06/30 12:39:15]

True.
I haven't yet decided on whether it should be documented which error it throws
in this case. It's not generally something the user can detect before calling,
so they need to catch the error. For that reason we might want to specify which
error object is thrown.
The actual error would probably be UnsupportedError (ArgumentError could be
argued, but it's not that the argument is bad, it just that there is no solution
to the question you are asking, RangeError doesn't fit). Maybe we should even
have an ArithmeticException - because its something the user will want to catch,
so it should be an exception.

Or we could just return 0, which is never a valid inverse.

    */
   int modInverse(int modulus);
 
   /**
    * Returns the greatest common divisor of the absolute value of
    * this integer and the absolute value of [other].
    *
    * Both this and [other] must be non-zero.
    */
   int gcd(int other);
@@ skipping 171 matching lines @@
    *     var value = int.parse(text, onError: (source) => null);
    *     if (value == null) ... handle the problem
    *
    * The [onError] function is only invoked if [source] is a [String]. It is
    * not invoked if the [source] is, for example, `null`.
    */
   external static int parse(String source,
                             { int radix,
                               int onError(String source) });
 }