java.text.ChoiceFormat pattern behavior is not well documented.

Summary

Improve the specification regarding the ChoiceFormat pattern in the class description, methods, and constructor.

Problem

A ChoiceFormat object can either be constructed/set using a limit and formats array, or a String pattern (which is a representation of those arrays). The class description provides an example of a pattern, however, there is no well-defined syntax for actually creating such a pattern. All of the other Format classes that use pattern Strings have sections on creating the associated pattern, ChoiceFormat is alone in not having such a section. The methods related to the pattern are also under-specified, and provide no links to further documentation. There are some additional general improvements that can be made to the API doc.

Solution

Create a pattern section which provides a well-defined and precise syntax for creating a ChoiceFormat pattern.

Additionally, make updates to the class description, methods, and constructors related to the pattern where appropriate.

For reference, an example ChoiceFormat pattern -> "-1#is negative| 0#is zero or fraction | 1#is one |1.0<is 1+ |2#is two |2<is more than 2."

Specification

Trivial example changes, and changes to use the {@return} tag were omitted for brevity.

General Class Description Changes

--- a/src/java.base/share/classes/java/text/ChoiceFormat.java
+++ b/src/java.base/share/classes/java/text/ChoiceFormat.java

 /**
- * A {@code ChoiceFormat} allows you to attach a format to a range of numbers.
- * It is generally used in a {@code MessageFormat} for handling plurals.
+ * {@code ChoiceFormat} is a concrete subclass of {@code NumberFormat} that
+ * allows you to attach a format to a range of numbers.
+ * It is generally used in a {@link MessageFormat} for handling plurals.
  * The choice is specified with an ascending list of doubles, where each item
  * specifies a half-open interval up to the next item:
  * <blockquote>
@@ -68,8 +69,10 @@
  * {@code ChoiceFormat} doesn't implement any locale specific behavior.
  *
  * <p>
- * When creating a {@code ChoiceFormat}, you must specify an array of formats
- * and an array of limits. The length of these arrays must be the same.
+ * A {@code ChoiceFormat} can be constructed using either an array of formats
+ * and an array of limits or a string pattern. When constructing with
+ * format and limit arrays, the length of these arrays must be the same.
+ *
@@ -83,7 +86,8 @@
  * <p>
- * Here is a simple example that shows formatting and parsing:
+ * Below is an example of constructing a ChoiceFormat with arrays to format
+ * and parse values:
  * <blockquote>
@@ -97,7 +101,8 @@
  * }
  * }
  * </blockquote>
- * Here is a more complex example, with a pattern format:
+ * For more sophisticated patterns, {@code ChoiceFormat} can be used with
+ * {@link MessageFormat} to produce accurate forms for singular and plural:
  * <blockquote>
@@ -114,42 +119,62 @@
  * }
  * </blockquote>
- * <p>
- * Specifying a pattern for ChoiceFormat objects is fairly straightforward.
- * For example:
+ * Would output the following:
+ * <blockquote>
+ * <pre>{@code
+ * There are no files on ADisk
+ * There is one file on ADisk
+ * There are 2 files on ADisk
+ * There are 3 files on ADisk
+ * }</pre>
+ * </blockquote>
+ *

Pattern Syntax (added to class description)

+ * <h2><a id="patterns">Patterns</a></h2>
+ * A {@code ChoiceFormat} pattern has the following syntax:
+ * <blockquote><pre>
+ * <i>Pattern:</i>
+ *         SubPattern *("|" SubPattern)
+ *         <i>Note: Each additional subPattern must have a limit greater than the previous subPattern's limit</i>
+ * <i>SubPattern:</i>
+ *         Limit Relation Format
+ * <i>Limit:</i>
+ *          Number / "&infin;" / "-&infin;"
+ * <i>Number:</i>
+ *         *(Digit) 1*(Decimal / Digit) *(Digit) [Exponent]
+ * <i>Decimal:</i>
+ *         1*(Digit ".") / 1*("." Digit)
+ * <i>Digit:</i>
+ *         0 - 9
+ * <i>Exponent:</i>
+ *         *(Digit) Digit ExponentSymbol Digit *(Digit)
+ * <i>ExponentSymbol:</i>
+ *         "e" / "E"
+ * <i>Relation:</i>
+ *         "#" / "&lt;" / "&le;"
+ * <i>Format:</i>
+ *         Any characters except the <i>Relation</i> symbols
+ * </pre></blockquote>
+ *
+ * <i>Note:The relation &le; is not equivalent to &lt;&equals;</i>
+ *
+ * <p>Below is an example of constructing a ChoiceFormat with a pattern:
  * <blockquote>

Method / Constructor Improvements

     /**
-     * Sets the pattern.
-     * @param newPattern See the class description.
+     * Apply the given pattern to this ChoiceFormat object. The syntax
+     * for the ChoiceFormat pattern can be seen in the {@linkplain ##patterns
+     * Patterns} section.
+     *
+     * @param newPattern a pattern string
      * @throws    NullPointerException if {@code newPattern}
      *            is {@code null}
      * @throws    IllegalArgumentException if {@code newPattern}
-     *            is invalid
+     *            violates the pattern syntax
+     * @see #ChoiceFormat(String)
      */
     public void applyPattern(String newPattern) {

     /**
-     * Gets the pattern.
+     * {@return a pattern {@code string} that represents the the limits and formats
+     * of this ChoiceFormat object}
+     *
+     * The {@code string} returned is not guaranteed to be the same input
+     * {@code string} passed to either {@link #applyPattern(String)} or
+     * {@link #ChoiceFormat(String)}.
      *
-     * @return the pattern string
+     * @see #applyPattern(String)
      */
     public String toPattern() {

     /**
-     * Constructs with limits and corresponding formats based on the pattern.
+     * Constructs a ChoiceFormat with limits and corresponding formats
+     * based on the pattern.
+     * The syntax for the ChoiceFormat pattern can be seen in the {@linkplain
+     * ##patterns Patterns} section.
      *
      * @param newPattern the new pattern string
      * @throws    NullPointerException if {@code newPattern} is
      *            {@code null}
      * @throws    IllegalArgumentException if {@code newPattern}
-     *            is invalid
+     *            violates the pattern syntax
      * @see #applyPattern
      */
     public ChoiceFormat(String newPattern)  {