Summary

Update and reformat the class descriptions for java.text.NumberFormat, and two relevant subclasses, DecimalFormat and CompactNumberFormat.

Problem

In general, the classes could improve readability from implementing basic changes such as better visual spacing and headers. There are also a few cases of outdated information that should be updated to reflect the current state of the classes.

Solution

Reformat the class descriptions to improve readability. This reformatting makes the three classes share the same structure, ("Getting a XXXFormat", "Using a XXXFormat", ...) which makes them easier to understand. Other changes includes adding headers, moving the pattern sections to the bottom, and general wording improvements. The pattern section is moved to the bottom, as patterns may not be relevant for users who are only relying on factory methods, which is the recommended way to get a NumberFormat.

While there are numerous changes to improve readability, some content changes are

• Introduce the concept of the Locale-sensitive service implementation for the factory methods
• Correct the false claim that a try block should be used to recover from an unsupported Locale for a factory method call. In reality, the parent locale chain will be looked up, and a Locale used as a fallback that is supported.
• Provide an example for retrieving a NumberFormat with Locale Extensions. Also update with the "cf" extension.
• Correct the DecimalFormat Special Values section for "Not a Number" from U+FFFD to NaN.
• Give an example of using the CompactNumberFormat constructor, (which is helpful, as it's not easily apparent how to use it)
• Add the Localized Symbol column to the DecimalFormat special pattern characters section. (Both localized and non-localized symbols are supported).
• Make it apparent that the DecimalFormat special pattern character for exponents "E" is case sensitive. This is to address a separate issue, which expected both "e" and "E" to work.
• Add the setStrict(boolean) method to the "Customizing NumberFormat" section, which makes it apparent that the method can be used to toggle leniency.
• Remove setDecimalSeparatorAlwaysShown(boolean) from "Customizing NumberFormat". This method is an instance method that belongs to the concrete subclass DecimalFormat, and does not belong at the NumberFormat class description level.

Specification

See either the attached docs or spec-diff.