8335271: Specify the MessageFormat ArgumentIndex Implementation Limit

Reviewed-by: darcy, iris, naoto, rriggs

Author: Justin Lu

src/java.base/share/classes/java/text/MessageFormat.java

@@ -110,17 +110,21 @@
  * </pre></blockquote>
  *
  * <p>
- * The <i>ArgumentIndex</i> value is a non-negative integer written
+ * The {@code ArgumentIndex} value is a non-negative integer written
  * using the digits {@code '0'} through {@code '9'}, and represents an index into the
  * {@code arguments} array passed to the {@code format} methods
  * or the result array returned by the {@code parse} methods.
  * <p>
- * The <i>FormatType</i> and <i>FormatStyle</i> values are used to create
+ * Any constructor or method that takes a String pattern parameter will throw an {@code IllegalArgumentException} if the
+ * pattern contains an {@code ArgumentIndex} value that is equal to or exceeds an implementation limit.
+ * <p>
+ * The {@code FormatType} and {@code FormatStyle} values are used to create
  * a {@code Format} instance for the format element. The following
  * table shows how the values map to {@code Format} instances. These values
  * are case-insensitive when passed to {@link #applyPattern(String)}. Combinations
  * not shown in the table are illegal. A <i>SubformatPattern</i> must
  * be a valid pattern string for the {@code Format} subclass used.
+ * @implNote In the reference implementation, the limit of {@code ArgumentIndex} is 10,000.
  *
  * <table class="plain">
  * <caption style="display:none">Shows how FormatType and FormatStyle values map to Format instances</caption>