ICU-21203 ICU-21198 ICU-21479 Improve docs discoverability for NumberFormatter

See #1559

docs/userguide/format_parse/numbers/index.md

@@ -13,7 +13,7 @@ License & terms of use: http://www.unicode.org/copyright.html
 # Formatting Numbers
 
 Since ICU 60, the recommended mechanism for formatting numbers is 
-[`NumberFormatter`](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/numberformatter_8h.html)
+[`NumberFormatter`](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/numberformatter_8h.html#details)
 ([Java](https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/number/NumberFormatter.html)).  `NumberFormatter` supports the formatting of:
 
 - Decimal Formatting

icu4c/source/i18n/unicode/numberformatter.h

@@ -28,10 +28,9 @@
 
 /**
  * \file
- * \brief C++ API: Library for localized number formatting introduced in ICU 60.
- *
- * This library was introduced in ICU 60 to simplify the process of formatting localized number strings.
- * Basic usage examples:
+ * \brief C++ API: All-in-one formatter for localized numbers, currencies, and units.
+ * 
+ * For a full list of options, see icu::number::NumberFormatterSettings.
  *
  * <pre>
  * // Most basic usage:
@@ -2247,6 +2246,9 @@ class U_I18N_API NumberFormatterSettings {
      * The returned skeleton is in normalized form, such that two number formatters with equivalent
      * behavior should produce the same skeleton.
      *
+     * For more information on number skeleton strings, see:
+     * https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html
+     *
      * @return A number skeleton string with behavior corresponding to this number formatter.
      * @stable ICU 62
      */
@@ -2779,6 +2781,9 @@ class U_I18N_API NumberFormatter final {
      * It is possible for an error to occur while parsing. See the overload of this method if you are
      * interested in the location of a possible parse error.
      *
+     * For more information on number skeleton strings, see:
+     * https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html
+     *
      * @param skeleton
      *            The skeleton string off of which to base this NumberFormatter.
      * @param status
@@ -2795,6 +2800,9 @@ class U_I18N_API NumberFormatter final {
      * If an error occurs while parsing the skeleton string, the offset into the skeleton string at
      * which the error occurred will be saved into the UParseError, if provided.
      *
+     * For more information on number skeleton strings, see:
+     * https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html
+     *
      * @param skeleton
      *            The skeleton string off of which to base this NumberFormatter.
      * @param perror

icu4c/source/i18n/unicode/unum.h

@@ -692,6 +692,12 @@ unum_formatDecimal(    const    UNumberFormat*  fmt,
 /**
  * Format a double currency amount using a UNumberFormat.
  * The double will be formatted according to the UNumberFormat's locale.
+ *
+ * To format an exact decimal value with a currency, use
+ * `unum_setTextAttribute(UNUM_CURRENCY_CODE, ...)` followed by unum_formatDecimal.
+ * Your UNumberFormat must be created with the UNUM_CURRENCY style. Alternatively,
+ * consider using unumf_openForSkeletonAndLocale.
+ *
  * @param fmt the formatter to use
  * @param number the number to format
  * @param currency the 3-letter null-terminated ISO 4217 currency code

icu4c/source/i18n/unicode/unumberformatter.h

@@ -468,6 +468,9 @@ typedef struct UFormattedNumber UFormattedNumber;
  * For more details on skeleton strings, see the documentation in numberformatter.h. For more details on
  * the usage of this API, see the documentation at the top of unumberformatter.h.
  *
+ * For more information on number skeleton strings, see:
+ * https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html
+ *
  * NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead.
  *
  * @param skeleton The skeleton string, like u"percent precision-integer"
@@ -485,6 +488,9 @@ unumf_openForSkeletonAndLocale(const UChar* skeleton, int32_t skeletonLen, const
  * Like unumf_openForSkeletonAndLocale, but accepts a UParseError, which will be populated with the
  * location of a skeleton syntax error if such a syntax error exists.
  *
+ * For more information on number skeleton strings, see:
+ * https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html
+ *
  * @param skeleton The skeleton string, like u"percent precision-integer"
  * @param skeletonLen The number of UChars in the skeleton string, or -1 if it is NUL-terminated.
  * @param locale The NUL-terminated locale ID.

icu4c/source/test/cintltst/cnumtst.c

@@ -75,6 +75,7 @@ static void TestSetMaxFracAndRoundIncr(void);
 static void TestIgnorePadding(void);
 static void TestSciNotationMaxFracCap(void);
 static void TestMinIntMinFracZero(void);
+static void Test21479_ExactCurrency(void);
 
 #define TESTCASE(x) addTest(root, &x, "tsformat/cnumtst/" #x)
 
@@ -116,6 +117,7 @@ void addNumForTest(TestNode** root)
     TESTCASE(TestIgnorePadding);
     TESTCASE(TestSciNotationMaxFracCap);
     TESTCASE(TestMinIntMinFracZero);
+    TESTCASE(Test21479_ExactCurrency);
 }
 
 /* test Parse int 64 */
@@ -3576,4 +3578,23 @@ static void TestMinIntMinFracZero(void) {
     }
 }
 
+static void Test21479_ExactCurrency(void) {
+    UErrorCode status = U_ZERO_ERROR;
+    UNumberFormat* nf = unum_open(UNUM_CURRENCY, NULL, 0, "en_US", NULL, &status);
+    if ( U_FAILURE(status) ) {
+        log_data_err("unum_open UNUM_CURRENCY for en_US fails with %s\n", u_errorName(status));
+        goto cleanup;
+    }
+    unum_setTextAttribute(nf, UNUM_CURRENCY_CODE, u"EUR", -1, &status);
+    UChar result[40];
+    unum_formatDecimal(nf, "987654321000000000000001", -1, result, 40, NULL, &status);
+    if (!assertSuccess("Formatting currency decimal", &status)) {
+        goto cleanup;
+    }
+    assertUEquals("", u"€987,654,321,000,000,000,000,001.00", result);
+
+    cleanup:
+    unum_close(nf);
+}
+
 #endif /* #if !UCONFIG_NO_FORMATTING */

icu4j/main/classes/core/src/com/ibm/icu/number/NumberFormatter.java

@@ -9,8 +9,9 @@ import com.ibm.icu.text.DecimalFormatSymbols;
 import com.ibm.icu.util.ULocale;
 
 /**
- * The main entrypoint to the localized number formatting library introduced in ICU 60. Basic usage
- * examples:
+ * All-in-one formatter for localized numbers, currencies, and units.
+ *
+ * For a full list of options, see {@link NumberFormatterSettings}.
  *
  * <pre>
  * // Most basic usage:
@@ -477,6 +478,9 @@ public final class NumberFormatter {
      * Call this method at the beginning of a NumberFormatter fluent chain to create an instance based
      * on a given number skeleton string.
      *
+     * For more information on number skeleton strings, see:
+     * https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html
+     *
      * @param skeleton
      *            The skeleton string off of which to base this NumberFormatter.
      * @return An {@link UnlocalizedNumberFormatter}, to be used for chaining.

icu4j/main/classes/core/src/com/ibm/icu/number/NumberFormatterSettings.java

@@ -605,6 +605,9 @@ public abstract class NumberFormatterSettings<T extends NumberFormatterSettings<
      * <p>
      * The returned skeleton is in normalized form, such that two number formatters with equivalent
      * behavior should produce the same skeleton.
+     * <p>
+     * For more information on number skeleton strings, see:
+     * https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html
      *
      * @return A number skeleton string with behavior corresponding to this number formatter.
      * @throws UnsupportedOperationException