Summary

Clarify the limitations of recursive MessageFormat patterns within a ChoiceFormat subformat.

Problem

MessageFormat contains subformats as long as it is an instanceof Format. One such class, ChoiceFormat, allows recursive MessageFormat patterns within it's own pattern. This behavior can be used for example, to create representations of singular and plural in messages for i18n.

ChoiceFormat has an example of this in the class specification that is incorrect. This example is currently misleading any users who are referencing it.

Solution

Replace the incorrect example with a correct one. Update the wording under the examples to clarify the limitations of achieving the recursive behavior.

Specification

(Example changes omitted)

In ChoiceFormat, under the example,

+ * See {@link MessageFormat##pattern_caveats MessageFormat} for caveats regarding
+ * {@code MessageFormat} patterns within a {@code ChoiceFormat} pattern.

In MessageFormat, under the example,

- * <strong>Note:</strong> As we see above, the string produced
- * by a {@code ChoiceFormat} in {@code MessageFormat} is treated as special;
- * occurrences of '{' are used to indicate subformats, and cause recursion.
+ * <strong id="pattern_caveats">Notes:</strong> As seen in the previous snippet,
+ * the string produced by a {@code ChoiceFormat} in {@code MessageFormat} is
+ * treated as special; occurrences of '{' are used to indicate subformats, and
+ * cause recursion. If a {@code FormatElement} is defined in the {@code ChoiceFormat}
+ * pattern, it will only be formatted according to the {@code FormatType} and
+ * {@code FormatStyle} pattern provided. The associated subformats of the
+ * top level {@code MessageFormat} will not be applied to the {@code FormatElement}
+ * defined in the {@code ChoiceFormat} pattern.