[loc-en-dev] [Fwd: Updated JavaDoc]

[Yoshito Umaoka]

Yoshito's comment in this color.
> Fowarding the message from Mark Davis below -
> -------------------------
>
> Because a |Locale| object is just an identifier for a region, no 
> validity check is performed when you construct a |Locale|.
>
> Add text indicating that it is strongly recommended that only valid 
> Unicode locale idenfiers be used in constructing locales.
I propose to explain about well-formed Locale and arbitrary Locale in 
the JavaDoc for the class.  We definitely need to explain what was will 
be changed in JDK7.

>
>
> |static java.lang.String[]| 	|*getISOCountries 
> <http://sites.google.com/site/java/util/Locale.html#getISOCountries%28%29>*()| 
>
>           Returns a list of all 2-letter country codes defined in ISO 
> 3166.
> |static java.lang.String[]| 	|*getISOLanguages 
> <http://sites.google.com/site/java/util/Locale.html#getISOLanguages%28%29>*()| 
>
>           Returns a list of all 2-letter language codes defined in ISO 
> 639.
>
>
> Deprecate these. Note in the text that while the original purpose of 
> these was to supply the components used in forming Locales, the 
> standard definition has moved beyond them.
>
> Ideally, we would add also:
> getBCP47BaseLanguages
> getBCP47Scripts
> getBCP47Regions
> getBCP47Variants
> but the OpenJDK group may not buy off on that. We could discuss it, 
> however.
>
I do not think these existing methods should be deprecated.  As Mark 
pointed out, the standard definition has moved beyond them, but it does 
not mean you cannot use a code returned by getISOCountries or 
getISOLanguages for a Locale.  We just go beyond them.

getBCP47xxxx might be useful (although I do not like the names), but I 
think it's optional for now.

>
>       SIMPLIFIED_CHINESE
>
> public static final Locale <http://sites.google.com/site/java/util/Locale.html> *SIMPLIFIED_CHINESE*
>
>     Useful constant for language. 
>
> ------------------------------------------------------------------------
>
>
>       TRADITIONAL_CHINESE
>
> public static final Locale <http://sites.google.com/site/java/util/Locale.html> *TRADITIONAL_CHINESE*
> Useful constant for language.
>
> Add notes that more properly speaking, these should be zh_Hans and 
> zh_Hant. However, for backwards compatibility these can continue to be 
> used. (I assume that the locale lookup is being changed to make these 
> essentially equal in lookup.)
>
> Update the language in various places, eg:
>
> Returns the language code for this locale, which will either be the 
> empty string or a lowercase ISO 639 code.
> => Returns the language code for this locale, which should either be 
> the empty string or a Unicode region identifier code.
>
I agree that the description must be updated.  (I did not touch existing 
JavaDoc for this time, but I know we'll need to do so)

> [Note, that language was always in conflict with the class 
> description, which had no absolute requirements on the code.]
>
>
>       getPrivateUse
>
> public java.lang.String *getPrivateUse*()
>
>     New API Returns the private use code for this locale. 
> I don't understand this.
>
I'd like to make Locale to duplicate BCP47 langtag (defined by the BNF, 
not Language-Tag) in Locale.  Of course, "privateuse" field is probably 
not used practically, but we want this for supporting canonical 
roundtrip between Locale and BCP47 language tag.  The valid syntax for 
BCP47 "privateuse" differs from singleton extension values.  So I prefer 
to handle "privateuse" field separated from other BCP47 singleton 
extensions.

>
> New API Returns a locale for the specified language tag string. If the 
> specified language tag contains any invalid subtags, the first invalid 
> subtag and all following subtags are ignored.
>
> Ignoring is dangerous... If it is ill-formed, it should raise an 
> exception.
>
I agree that we need "strict" version of Locale#forLanguageTag.  But at 
the same time, we also need "easy" version and this is the easy 
version.  I expect most people just use this version, rather than doing 
their own error handling.

> More later.
>
>
> Mark

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.openjdk.java.net/pipermail/locale-enhancement-dev/attachments/20090303/1e574096/attachment.html