[loc-en-dev] Revised Locale API proposal

[Steven R. Loomis]

Hello,
   I also mostly have readability comments, but they are minor. Here are 
a few items possibly worth discussing:

- Locale.Builder:    should 'initial, default state' say 'empty state'? 
We don't want to confuse it with the default locale.

- same comment with Locale.Builder.setScript - if the script is the 
empty string, the documentation should say what happens (Does it really 
get the default script for the locale ? Or does it remain empty, with 
the /effect/ of being default?)

 - Locale.Builder.setExtension:   I think 'x' and 'u' are swapped here, 
should be LDML_EXTENSION(u) and PRIVATE_USE_EXTENSION('x).

Steven

Doug Felt wrote:
> Looks good to me.  I can edit the text for readability in some places,
> but there's nothing significant.  I suggest not documenting
> NullPointerExceptions, but instead only documenting places where null
> is _accepted_ as a value, since you have to document what it means
> anyway, and this is in general rarer.
>
> Other comments::
> - Do we want LocaleNameProvider to be able to return a display name
> for a full locale?  It seems eventually data could provide more
> natural display names.
>
> - The Builder idiom (from Josh Bloch) uses 'build' instead of 'create'
> as the name for the method that returns the product of the builder.
> We should probably follow this.
>
> Doug
>
> On Tue, Sep 8, 2009 at 10:51 AM, Mark Davis ⌛<mark at macchiato.com> wrote:
>   
>> General: We should not be directly referencing ISO standards, because they
>> are unstable. We can often reference BCP 47 and the iana registry, but it is
>> more accurate to reference Unicode Locale Identifiers (LDML).
>>
>> Examples:
>>
>> ===
>>
>> getISOCountries
>>
>> public static java.lang.String[] getISOCountries()
>>
>> Returns a list of all 2-letter country codes defined in ISO 3166. Can be
>> used to create Locales.
>> Should be: returns all region codes in the iana registry, including both 2
>> letter ISO codes (current and deprecated) and 3 digit UN M.49 codes. (Either
>> that or we need to add a "real" method to get all the valid ones.)
>>
>> getISOLanguages
>>
>> public static java.lang.String[] getISOLanguages()
>>
>> Returns a list of all 2-letter language codes defined in ISO 639. Can be
>> used to create Locales. [NOTE: ISO 639 is not a stable standard-- some
>> languages' codes have changed. The list this function returns includes both
>> the new and the old codes for the languages whose codes have changed.]
>>
>> Should be: returns a list of all primary language codes defined in the iana
>> registry (includes 2 and 3 letter ISO 639 codes). (Either that or we need to
>> add a "real" method to get all the valid ones.)
>>
>> getVariant
>>
>> public java.lang.String getVariant()
>>
>> Returns the variant code for this locale, which should either be the empty
>> string or a conforming BCP47 variant string.
>> What about variants like "rozaj_biske"? [see
>> http://www.iana.org/assignments/language-subtag-registry] Does this method
>> return only the first subtag, or all? [My preference would be all, in
>> alphabetical order.] Similar issue for LocaleBuilder.setVariant
>>
>>
>> Mark
>>
>>
>> On Tue, Sep 8, 2009 at 10:07, Yoshito Umaoka <y.umaoka at gmail.com> wrote:
>>     
>>> Hi all,
>>>
>>> I reviewed the proposed API docs and updated followings -
>>>
>>> 1. Locale class description: Reorganized and provided more comprehensive
>>> explanation for logical locale fields.
>>> 2. Variant: Removed syntactical restrictions on variant, provided some
>>> note about BCP47 compatibility.
>>> 3. Mics changes: Consistent terminology, removed "New API", etc...
>>>
>>> I'm attaching a zip file in this message.  Please take a look if this
>>> version is good enough for submitting a proposal to OpenJDK.
>>>
>>> I'll add some explanation about the updated behavior for candidate list in
>>> ResourceBundle.Control and LocaleServiceProvider, but these are behavior
>>> changes, not adding/changing APIs.
>>>
>>> -Yoshito
>>>       
>>     


-- 
Steven R. Loomis  srl at icu-project.org
Technical Lead, ICU for C/C++   <http://icu-project.org>
IBM San José Globalization Center of Competency
<http://ibm.com/software/globalization>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.openjdk.java.net/pipermail/locale-enhancement-dev/attachments/20090908/7ed0b0f0/attachment.html