[Fmt-Ch] ChoiceFormat claims impossible and unimplemented functionality

FULL PRODUCT VERSION :
java version "1.6.0_07"
Java(TM) SE Runtime Environment (build 1.6.0_07-b06)
Java HotSpot(TM) Client VM (build 10.0-b23, mixed mode)


A DESCRIPTION OF THE PROBLEM :
The following is claimed in the documentation of setChoices (http://java.sun.com/javase/6/docs/api/java/text/ChoiceFormat.html#setChoices%28double%5B%5D,%20java.lang.String%5B%5D%29)

formats - are the formats you want to use for each limit. They can be either Format objects or Strings. When formatting with object Y, if the object is a NumberFormat, then ((NumberFormat) Y).format(X) is called. Otherwise Y.toString() is called.

However, since formats is declared as a String[], this claimed functionality is impossible to use. Further, looking at the source code, the format array is declared as String[], and despite comments insinuating the claimed functionality, it's never actually implemented.

            // return either a formatted number, or a string
            return toAppendTo.append(choiceFormats[i]);



REPRODUCIBILITY :
This bug can be reproduced always.

CUSTOMER SUBMITTED WORKAROUND :
There is no easy workaround if this functionality is desired. I see two possible course of action:

* Remove the claim of this functionality from the documentation (i.e. this is a report of a bug in the documentation)

* Implement the claimed functionality (i.e. this is a request for "enhancement", to implement a feature that was clearly planned for but for some reason abandoned).