ListFormatter bad / outdated documentation
Description
Attachments
duplicates
relates to
Steven R. Loomis
Activity
All of these APIs are marked "ICU internal"
In Java ListFormatter.Style is internal:
http://icu-project.org/apiref/icu4j/com/ibm/icu/text/ListFormatter.Style.html
And in C/C++ (taking a string) the createInstance method taking a style is internal:
http://icu-project.org/apiref/icu4c/classicu_1_1ListFormatter.html#a5eed49d6d65f32b12853519cad9960af
Between the fact that these APIs are internal, and the fact that "duration" and "duration-short" never worked it should be enough to document "or", "unit", "unit-narrow", "unit-short" / modify the Java enum.
We don't need to worry about backward compatibility.
I checked the history of CLDR:
21 .. 23.1 : "" // only one list pattern (and)
24 .. 31.0.1 : "", "unit", "unit-narrow", "unit-short"
32 .. latest : "", "or", "unit", "unit-narrow", "unit-short"
The "" maps to "standard" in ICU.
So it looks like "duration" and "duration-short" never worked
(unless there was some mapping in ICU that is now removed, which I doubt)
There is a C/C++ test unit for "unit-narrow"
Sorry for the extra noise... I thought that `this` works to mark something as "monospaced", like in most other markup languages...
The documentation for
is incorrect or outdated.
The values for `style` are listed as `"standard"`, `"duration"`, or `"duration-short"`
See the official doc:
http://icu-project.org/apiref/icu4c/classicu_1_1ListFormatter.html#a5eed49d6d65f32b12853519cad9960af
I have also checked the latest code in GitHub:
https://github.com/unicode-org/icu/blob/master/icu4c/source/i18n/unicode/listformatter.h#L189
On the other side, the latest CLDR data contains the following styles:
`"or"`, `"standard"`, `"unit"`, `"unit-narrow"`, `"unit-short"`
See https://github.com/unicode-org/icu/blob/master/icu4c/source/data/locales/en.txt#L1980
I have tried to write a small test to check the functionality.
I've created an extra test unit to check all the styles (doc + cldr).
git patch attached.
It confirms that the doc is bad (`"duration"` and `"duration-short"` fail with `U_MISSING_RESOURCE_ERROR`)
---------
If the CLDR data was like this for a while, and CLDR changed, then it is "just a documentation problem"
But if and older CLDR version had data for `"duration"` and `"duration-short"`, then at some point the old functionality was broken.
We need to update the doc (at least), and (maybe) create some aliases for the removed styles, if things used to work that way.
------------
Similar (but kind of worse) with Java.
But there the style is an enum. So there is no way to use "or" or "unit", only the old (and bad) values. Everything except for `STANDARD` will fail.
http://icu-project.org/apiref/icu4j/com/ibm/icu/text/ListFormatter.Style.html
We need to update the `ListFormatter.Style` enum