Cherry-pick: ICU-21020 Document unchecked exception in various number formatter classes am: 5b0eea5d7f

Change-Id: I5ebb68fb8f7ea7dd3e1cc569904d41eb65f88c9c

14 files changed, 36 insertions, 0 deletions

diff --git a/android_icu4j/src/main/java/android/icu/number/CurrencyPrecision.java b/android_icu4j/src/main/java/android/icu/number/CurrencyPrecision.java
index 65efc22be..654a69ea8 100644
--- a/android_icu4j/src/main/java/android/icu/number/CurrencyPrecision.java
+++ b/android_icu4j/src/main/java/android/icu/number/CurrencyPrecision.java
@@ -34,6 +34,7 @@ public abstract class CurrencyPrecision extends Precision {
      * @param currency
      *            The currency to associate with this rounding strategy.
      * @return A Precision for chaining or passing to the NumberFormatter rounding() setter.
+     * @throws IllegalArgumentException for null Currency
      * @see NumberFormatter
      */
     public Precision withCurrency(Currency currency) {
diff --git a/android_icu4j/src/main/java/android/icu/number/FractionPrecision.java b/android_icu4j/src/main/java/android/icu/number/FractionPrecision.java
index 7e9aa6627..9b301d9ef 100644
--- a/android_icu4j/src/main/java/android/icu/number/FractionPrecision.java
+++ b/android_icu4j/src/main/java/android/icu/number/FractionPrecision.java
@@ -34,6 +34,7 @@ public abstract class FractionPrecision extends Precision {
      * @param minSignificantDigits
      *            The number of significant figures to guarantee.
      * @return A Precision for chaining or passing to the NumberFormatter rounding() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than 1.
      * @see NumberFormatter
      */
     public Precision withMinDigits(int minSignificantDigits) {
@@ -61,6 +62,7 @@ public abstract class FractionPrecision extends Precision {
      * @param maxSignificantDigits
      *            Round the number to no more than this number of significant figures.
      * @return A Precision for chaining or passing to the NumberFormatter rounding() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than 1.
      * @see NumberFormatter
      */
     public Precision withMaxDigits(int maxSignificantDigits) {
diff --git a/android_icu4j/src/main/java/android/icu/number/IntegerWidth.java b/android_icu4j/src/main/java/android/icu/number/IntegerWidth.java
index 48cc52862..9ff75ad68 100644
--- a/android_icu4j/src/main/java/android/icu/number/IntegerWidth.java
+++ b/android_icu4j/src/main/java/android/icu/number/IntegerWidth.java
@@ -35,6 +35,7 @@ public class IntegerWidth {
      * @param minInt
      *            The minimum number of places before the decimal separator.
      * @return An IntegerWidth for chaining or passing to the NumberFormatter integerWidth() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than 0.
      * @see NumberFormatter
      */
     public static IntegerWidth zeroFillTo(int minInt) {
@@ -58,6 +59,7 @@ public class IntegerWidth {
      *            The maximum number of places before the decimal separator. maxInt == -1 means no
      *            truncation.
      * @return An IntegerWidth for passing to the NumberFormatter integerWidth() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than -1.
      * @see NumberFormatter
      */
     public IntegerWidth truncateAt(int maxInt) {
diff --git a/android_icu4j/src/main/java/android/icu/number/LocalizedNumberRangeFormatter.java b/android_icu4j/src/main/java/android/icu/number/LocalizedNumberRangeFormatter.java
index cc7ed6187..bb5b85741 100644
--- a/android_icu4j/src/main/java/android/icu/number/LocalizedNumberRangeFormatter.java
+++ b/android_icu4j/src/main/java/android/icu/number/LocalizedNumberRangeFormatter.java
@@ -67,6 +67,7 @@ public class LocalizedNumberRangeFormatter extends NumberRangeFormatterSettings<
      * @param second
      *            The second number in the range, usually to the right in LTR locales.
      * @return A FormattedNumberRange object; call .toString() to get the string.
+     * @throws IllegalArgumentException if first or second is null
      * @see NumberRangeFormatter
      */
     public FormattedNumberRange formatRange(Number first, Number second) {
diff --git a/android_icu4j/src/main/java/android/icu/number/Precision.java b/android_icu4j/src/main/java/android/icu/number/Precision.java
index 3049d44c2..f60520cd2 100644
--- a/android_icu4j/src/main/java/android/icu/number/Precision.java
+++ b/android_icu4j/src/main/java/android/icu/number/Precision.java
@@ -86,6 +86,7 @@ public abstract class Precision {
      *            The minimum and maximum number of numerals to display after the decimal separator
      *            (rounding if too long or padding with zeros if too short).
      * @return A FractionPrecision for chaining or passing to the NumberFormatter precision() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than 0.
      * @see NumberFormatter
      */
     public static FractionPrecision fixedFraction(int minMaxFractionPlaces) {
@@ -110,6 +111,7 @@ public abstract class Precision {
      *            The minimum number of numerals to display after the decimal separator (padding with
      *            zeros if necessary).
      * @return A FractionPrecision for chaining or passing to the NumberFormatter precision() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than 0.
      * @see NumberFormatter
      */
     public static FractionPrecision minFraction(int minFractionPlaces) {
@@ -131,6 +133,7 @@ public abstract class Precision {
      *            The maximum number of numerals to display after the decimal mark (rounding if
      *            necessary).
      * @return A FractionPrecision for chaining or passing to the NumberFormatter precision() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than 0.
      * @see NumberFormatter
      */
     public static FractionPrecision maxFraction(int maxFractionPlaces) {
@@ -155,6 +158,7 @@ public abstract class Precision {
      *            The maximum number of numerals to display after the decimal separator (rounding if
      *            necessary).
      * @return A FractionPrecision for chaining or passing to the NumberFormatter precision() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than 0.
      * @see NumberFormatter
      */
     public static FractionPrecision minMaxFraction(int minFractionPlaces, int maxFractionPlaces) {
@@ -181,6 +185,7 @@ public abstract class Precision {
      *            The minimum and maximum number of significant digits to display (rounding if too long
      *            or padding with zeros if too short).
      * @return A Precision for chaining or passing to the NumberFormatter precision() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than 1.
      * @see NumberFormatter
      */
     public static Precision fixedSignificantDigits(int minMaxSignificantDigits) {
@@ -204,6 +209,7 @@ public abstract class Precision {
      * @param minSignificantDigits
      *            The minimum number of significant digits to display (padding with zeros if too short).
      * @return A Precision for chaining or passing to the NumberFormatter precision() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than 1.
      * @see NumberFormatter
      */
     public static Precision minSignificantDigits(int minSignificantDigits) {
@@ -222,6 +228,7 @@ public abstract class Precision {
      * @param maxSignificantDigits
      *            The maximum number of significant digits to display (rounding if too long).
      * @return A Precision for chaining or passing to the NumberFormatter precision() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than 1.
      * @see NumberFormatter
      */
     public static Precision maxSignificantDigits(int maxSignificantDigits) {
@@ -243,6 +250,7 @@ public abstract class Precision {
      * @param maxSignificantDigits
      *            The maximum number of significant digits to display (rounding if necessary).
      * @return A Precision for chaining or passing to the NumberFormatter precision() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than 1.
      * @see NumberFormatter
      */
     public static Precision minMaxSignificantDigits(int minSignificantDigits, int maxSignificantDigits) {
@@ -277,6 +285,7 @@ public abstract class Precision {
      * @param roundingIncrement
      *            The increment to which to round numbers.
      * @return A Precision for chaining or passing to the NumberFormatter precision() setter.
+     * @throws IllegalArgumentException if the rounding increment is null or non-positive.
      * @see NumberFormatter
      */
     public static Precision increment(BigDecimal roundingIncrement) {
@@ -303,6 +312,7 @@ public abstract class Precision {
      *            Either STANDARD (for digital transactions) or CASH (for transactions where the rounding
      *            increment may be limited by the available denominations of cash or coins).
      * @return A CurrencyPrecision for chaining or passing to the NumberFormatter precision() setter.
+     * @throws IllegalArgumentException if currencyUsage is null.
      * @see NumberFormatter
      */
     public static CurrencyPrecision currency(CurrencyUsage currencyUsage) {
diff --git a/android_icu4j/src/main/java/android/icu/number/ScientificNotation.java b/android_icu4j/src/main/java/android/icu/number/ScientificNotation.java
index d5637afe3..145ecb1cb 100644
--- a/android_icu4j/src/main/java/android/icu/number/ScientificNotation.java
+++ b/android_icu4j/src/main/java/android/icu/number/ScientificNotation.java
@@ -56,6 +56,7 @@ public class ScientificNotation extends Notation {
      * @param minExponentDigits
      *            The minimum number of digits to show in the exponent.
      * @return A ScientificNotation, for chaining.
+     * @throws IllegalArgumentException if minExponentDigits is too big or smaller than 1
      * @see NumberFormatter
      */
     public ScientificNotation withMinExponentDigits(int minExponentDigits) {
diff --git a/android_icu4j/src/main/java/android/icu/text/FormattedValue.java b/android_icu4j/src/main/java/android/icu/text/FormattedValue.java
index 278a1248b..02daa93c7 100644
--- a/android_icu4j/src/main/java/android/icu/text/FormattedValue.java
+++ b/android_icu4j/src/main/java/android/icu/text/FormattedValue.java
@@ -35,6 +35,7 @@ public interface FormattedValue extends CharSequence {
      *
      * @param appendable The Appendable to which to append the string output.
      * @return The same Appendable, for chaining.
+     * @throws ICUUncheckedIOException if the Appendable throws IOException
      * @hide draft / provisional / internal are hidden on Android
      */
     public <A extends Appendable> A appendTo(A appendable);
diff --git a/icu4j/main/classes/core/src/com/ibm/icu/number/CurrencyPrecision.java b/icu4j/main/classes/core/src/com/ibm/icu/number/CurrencyPrecision.java
index a174ec90d..586186735 100644
--- a/icu4j/main/classes/core/src/com/ibm/icu/number/CurrencyPrecision.java
+++ b/icu4j/main/classes/core/src/com/ibm/icu/number/CurrencyPrecision.java
@@ -34,6 +34,7 @@ public abstract class CurrencyPrecision extends Precision {
      * @param currency
      *            The currency to associate with this rounding strategy.
      * @return A Precision for chaining or passing to the NumberFormatter rounding() setter.
+     * @throws IllegalArgumentException for null Currency
      * @stable ICU 60
      * @see NumberFormatter
      */
diff --git a/icu4j/main/classes/core/src/com/ibm/icu/number/FractionPrecision.java b/icu4j/main/classes/core/src/com/ibm/icu/number/FractionPrecision.java
index 107389ea6..3727f1c0e 100644
--- a/icu4j/main/classes/core/src/com/ibm/icu/number/FractionPrecision.java
+++ b/icu4j/main/classes/core/src/com/ibm/icu/number/FractionPrecision.java
@@ -34,6 +34,7 @@ public abstract class FractionPrecision extends Precision {
      * @param minSignificantDigits
      *            The number of significant figures to guarantee.
      * @return A Precision for chaining or passing to the NumberFormatter rounding() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than 1.
      * @stable ICU 60
      * @see NumberFormatter
      */
@@ -62,6 +63,7 @@ public abstract class FractionPrecision extends Precision {
      * @param maxSignificantDigits
      *            Round the number to no more than this number of significant figures.
      * @return A Precision for chaining or passing to the NumberFormatter rounding() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than 1.
      * @stable ICU 60
      * @see NumberFormatter
      */
diff --git a/icu4j/main/classes/core/src/com/ibm/icu/number/IntegerWidth.java b/icu4j/main/classes/core/src/com/ibm/icu/number/IntegerWidth.java
index c3571099f..4ba85bb9f 100644
--- a/icu4j/main/classes/core/src/com/ibm/icu/number/IntegerWidth.java
+++ b/icu4j/main/classes/core/src/com/ibm/icu/number/IntegerWidth.java
@@ -35,6 +35,7 @@ public class IntegerWidth {
      * @param minInt
      *            The minimum number of places before the decimal separator.
      * @return An IntegerWidth for chaining or passing to the NumberFormatter integerWidth() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than 0.
      * @stable ICU 60
      * @see NumberFormatter
      */
@@ -59,6 +60,7 @@ public class IntegerWidth {
      *            The maximum number of places before the decimal separator. maxInt == -1 means no
      *            truncation.
      * @return An IntegerWidth for passing to the NumberFormatter integerWidth() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than -1.
      * @stable ICU 60
      * @see NumberFormatter
      */
diff --git a/icu4j/main/classes/core/src/com/ibm/icu/number/LocalizedNumberRangeFormatter.java b/icu4j/main/classes/core/src/com/ibm/icu/number/LocalizedNumberRangeFormatter.java
index b7d875d29..aca413f24 100644
--- a/icu4j/main/classes/core/src/com/ibm/icu/number/LocalizedNumberRangeFormatter.java
+++ b/icu4j/main/classes/core/src/com/ibm/icu/number/LocalizedNumberRangeFormatter.java
@@ -69,6 +69,7 @@ public class LocalizedNumberRangeFormatter extends NumberRangeFormatterSettings<
      * @param second
      *            The second number in the range, usually to the right in LTR locales.
      * @return A FormattedNumberRange object; call .toString() to get the string.
+     * @throws IllegalArgumentException if first or second is null
      * @stable ICU 63
      * @see NumberRangeFormatter
      */
diff --git a/icu4j/main/classes/core/src/com/ibm/icu/number/Precision.java b/icu4j/main/classes/core/src/com/ibm/icu/number/Precision.java
index 3a70c79de..9999241e8 100644
--- a/icu4j/main/classes/core/src/com/ibm/icu/number/Precision.java
+++ b/icu4j/main/classes/core/src/com/ibm/icu/number/Precision.java
@@ -88,6 +88,7 @@ public abstract class Precision {
      *            The minimum and maximum number of numerals to display after the decimal separator
      *            (rounding if too long or padding with zeros if too short).
      * @return A FractionPrecision for chaining or passing to the NumberFormatter precision() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than 0.
      * @stable ICU 60
      * @see NumberFormatter
      */
@@ -113,6 +114,7 @@ public abstract class Precision {
      *            The minimum number of numerals to display after the decimal separator (padding with
      *            zeros if necessary).
      * @return A FractionPrecision for chaining or passing to the NumberFormatter precision() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than 0.
      * @stable ICU 60
      * @see NumberFormatter
      */
@@ -135,6 +137,7 @@ public abstract class Precision {
      *            The maximum number of numerals to display after the decimal mark (rounding if
      *            necessary).
      * @return A FractionPrecision for chaining or passing to the NumberFormatter precision() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than 0.
      * @stable ICU 60
      * @see NumberFormatter
      */
@@ -160,6 +163,7 @@ public abstract class Precision {
      *            The maximum number of numerals to display after the decimal separator (rounding if
      *            necessary).
      * @return A FractionPrecision for chaining or passing to the NumberFormatter precision() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than 0.
      * @stable ICU 60
      * @see NumberFormatter
      */
@@ -187,6 +191,7 @@ public abstract class Precision {
      *            The minimum and maximum number of significant digits to display (rounding if too long
      *            or padding with zeros if too short).
      * @return A Precision for chaining or passing to the NumberFormatter precision() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than 1.
      * @stable ICU 62
      * @see NumberFormatter
      */
@@ -211,6 +216,7 @@ public abstract class Precision {
      * @param minSignificantDigits
      *            The minimum number of significant digits to display (padding with zeros if too short).
      * @return A Precision for chaining or passing to the NumberFormatter precision() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than 1.
      * @stable ICU 62
      * @see NumberFormatter
      */
@@ -230,6 +236,7 @@ public abstract class Precision {
      * @param maxSignificantDigits
      *            The maximum number of significant digits to display (rounding if too long).
      * @return A Precision for chaining or passing to the NumberFormatter precision() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than 1.
      * @stable ICU 62
      * @see NumberFormatter
      */
@@ -252,6 +259,7 @@ public abstract class Precision {
      * @param maxSignificantDigits
      *            The maximum number of significant digits to display (rounding if necessary).
      * @return A Precision for chaining or passing to the NumberFormatter precision() setter.
+     * @throws IllegalArgumentException if the input number is too big or smaller than 1.
      * @stable ICU 62
      * @see NumberFormatter
      */
@@ -287,6 +295,7 @@ public abstract class Precision {
      * @param roundingIncrement
      *            The increment to which to round numbers.
      * @return A Precision for chaining or passing to the NumberFormatter precision() setter.
+     * @throws IllegalArgumentException if the rounding increment is null or non-positive.
      * @stable ICU 60
      * @see NumberFormatter
      */
@@ -314,6 +323,7 @@ public abstract class Precision {
      *            Either STANDARD (for digital transactions) or CASH (for transactions where the rounding
      *            increment may be limited by the available denominations of cash or coins).
      * @return A CurrencyPrecision for chaining or passing to the NumberFormatter precision() setter.
+     * @throws IllegalArgumentException if currencyUsage is null.
      * @stable ICU 60
      * @see NumberFormatter
      */
diff --git a/icu4j/main/classes/core/src/com/ibm/icu/number/ScientificNotation.java b/icu4j/main/classes/core/src/com/ibm/icu/number/ScientificNotation.java
index cc3dd7710..5c7d2e4d6 100644
--- a/icu4j/main/classes/core/src/com/ibm/icu/number/ScientificNotation.java
+++ b/icu4j/main/classes/core/src/com/ibm/icu/number/ScientificNotation.java
@@ -56,6 +56,7 @@ public class ScientificNotation extends Notation {
      * @param minExponentDigits
      *            The minimum number of digits to show in the exponent.
      * @return A ScientificNotation, for chaining.
+     * @throws IllegalArgumentException if minExponentDigits is too big or smaller than 1
      * @stable ICU 60
      * @see NumberFormatter
      */
diff --git a/icu4j/main/classes/core/src/com/ibm/icu/text/FormattedValue.java b/icu4j/main/classes/core/src/com/ibm/icu/text/FormattedValue.java
index 841a31336..5a0dd5bb0 100644
--- a/icu4j/main/classes/core/src/com/ibm/icu/text/FormattedValue.java
+++ b/icu4j/main/classes/core/src/com/ibm/icu/text/FormattedValue.java
@@ -35,6 +35,7 @@ public interface FormattedValue extends CharSequence {
      *
      * @param appendable The Appendable to which to append the string output.
      * @return The same Appendable, for chaining.
+     * @throws ICUUncheckedIOException if the Appendable throws IOException
      * @draft ICU 64
      * @provisional This API might change or be removed in a future release.
      */