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

[Doug Felt]

I'm going to revise and edit the javadoc comments, so we don't worry for now
about particulars of wording, just the overall semantics.

The tests express my understanding (as of this morning) of the semantics of
the APIs.  It would help to review them.  I'll write the javadocs based on
them but probably won't finish before the meeting this afternoon.

Doug

On Tue, Mar 3, 2009 at 1:45 PM, Yoshito Umaoka <y.umaoka at gmail.com> wrote:

>  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/39081df3/attachment.html