Summary

Correct the description about the default decomposition mode in java.text.Collator

Problem

The current javadoc for Collator.NO_DECOMPOSITION reads that it is the default decomposition mode, regardless of how the instance is created. But in fact, it is not correct in some cases. For example,

new RuleBasedCollator("< a< b< c< d").getDecomposition() == Collator.NO_DECOMPOSITION

is false. On the other hand, instances that are created with the factory method getInstance(Locale) default to Collator.NO_DECOMPOSITION mode.

Solution

Since the Collator class is abstract, it is up to each implementation to decide which the default decomposition mode is. That explanation about NO_DECOMPOSITION being the default in the Collator.NO_DECOMPOSITION field should be removed. Instead, Collator.getInstance(Locale) should identify the default values for strength/decomposition.

Specification

Modify the javadoc for NO_DECOMPOSITION field as:

     /**
      * Decomposition mode value. With NO_DECOMPOSITION
      * set, accented characters will not be decomposed for collation. This
-     * is the default setting and provides the fastest collation but
+     * setting provides the fastest collation but
      * will only produce correct results for languages that do not use accents.
      * @see java.text.Collator#getDecomposition
      * @see java.text.Collator#setDecomposition

Modify the javadoc for getInstance(Locale) method as:

@@ -242,11 +242,11 @@
      * <tr><th scope="row" style="text-align:left">level1</th>
      *     <td>PRIMARY</td></tr>
      * <tr><th scope="row" style="text-align:left">level2</th>
      *     <td>SECONDARY</td></tr>
      * <tr><th scope="row" style="text-align:left">level3</th>
-     *     <td>TERTIARY</td></tr>
+     *     <td>TERTIARY<sup>*</sup></td></tr>
      * <tr><th scope="row" style="text-align:left">identic</th>
      *     <td>IDENTICAL</td></tr>
      * </tbody>
      * <thead>
      * <tr><th scope="col">BCP 47 values for normalization (kk)</th>
@@ -254,13 +254,14 @@
      * </thead>
      * <tbody>
      * <tr><th scope="row" style="text-align:left">true</th>
      *     <td>CANONICAL_DECOMPOSITION</td></tr>
      * <tr><th scope="row" style="text-align:left">false</th>
-     *     <td>NO_DECOMPOSITION</td></tr>
+     *     <td>NO_DECOMPOSITION<sup>*</sup></td></tr>
      * </tbody>
      * </table>
+     * Asterisk (<sup>*</sup>) denotes the default value.
      * If the specified setting value is not recognized, the strength and/or
-     * decomposition will not be overridden, as if there were no BCP 47 collation
+     * decomposition is not overridden, as if there were no BCP 47 collation
      * options in the desired locale.