Summary

Update the inadequate ChoiceFormat#parse(String, ParsePosition) specification.

Problem

The specification for ChoiceFormat#parse(String, ParsePosition) simply states "Parses a Number from the input text" which does not indicate at all how the Number is returned. As the method returns Number and is named parse, the current wording does not provide any new information.

Solution

Provide a specification which reflects how the value is returned.

Additionally, provide wording which states that the Number sub-type is always Double, which allows callers to better utilize the returned value. There is no benefit in allowing flexibility of the sub-type for other implementations, since this method should return a ChoiceFormat limit, which is of type Double.

Specification

     /**
-     * Parses a Number from the input text.
+     * Parses the input text starting at the index given by the {@code ParsePosition}
+     * as a {@code Double}. The value returned is the {@code limit} corresponding
+     * to the {@code format} that is the longest substring of the input text.
+     * Matching is done in ascending order, when multiple {@code format}s match
+     * the text equivalently in strength, the first matching {@code limit} is
+     * returned. If there is no match, {@code Double.NaN} is returned.
+     * <p>
+     * For example,
+     * {@snippet lang=java :
+     * var fmt = new ChoiceFormat("0#foo|1#bar|2#baz");
+     * fmt.parse("baz", new ParsePosition(0)); // returns 2.0
+     * fmt.parse("quux", new ParsePosition(0)); // returns NaN
+     * }
+     *
      * @param text the source text.
      * @param status an input-output parameter.  On input, the
      * status.index field indicates the first character of the
@@ -567,7 +580,8 @@
      * in the source text.  On exit, if an error did occur,
      * status.index is unchanged and status.errorIndex is set to the
      * first index of the character that caused the parse to fail.
-     * @return A Number representing the value of the number parsed.
+     * @return A Number which represents the {@code limit} corresponding to the
+     * {@code format} parsed, or {@code Double.NaN} if the parse fails.