I should really be doing something else, but I reworked my "surrogate readability patch" http://cr.openjdk.java.net/~martin/webrevs/openjdk7/isSurrogate2/ to take into account Joe's suggestions.
Masayoshi, hope that's OK with you. The new javadoc makes the values of various jsr 204 constants more obvious than before. I intend to fold the two isSurrogate patches into one and commit them when I get CCC approval. Speaking of which... has that happened yet? Martin On Wed, Aug 5, 2009 at 09:37, Joseph D. Darcy<joe.da...@sun.com> wrote: > Martin Buchholz wrote: >> >> Hi Masayoshi, >> >> Hmmm, >> I was thinking "but all you have to do to get the actual value >> is follow the @link to the constant (e.g. MAX_SURROGATE)" >> but I tried that but... for example... >> >> http://download.java.net/jdk7/docs/api/java/lang/Character.html#MAX_SURROGATE >> does not document the hex value. >> >> I think *that's* where we should move the description of the hex value. >> I propose to modify my patch in that way. >> >> (The hex values are also documented in the Character class comment) >> > > Yes, I agree it is perfectly reasonable and informative for the MAX_FOO > documentation to say "MAX_FOO is 0xabcd". That is the right place for such > detailed information. > In contrast, I don't find the isFoo method's documentation saying > "Returns true if c >= 0x1234 && c <= 0xabcd" > when the actual code uses the more readable > "return c >= MIN_FOO && c <= MAX_FOO" > to be kind to readers of the javadoc! > > -Joe > >> Martin >> >> On Tue, Aug 4, 2009 at 22:34, Masayoshi Okutsu<masayoshi.oku...@sun.com> >> wrote: >> >>> >>> Hi Martin, >>> >>> I vaguely remember that we (jsr204) followed the convention of the >>> Character >>> class to mention Unicode values in the API doc. It's also convenient to >>> have >>> Unicode values because you don't need to look up the Unicode standards. I >>> don't see much value to rewrite the existing descriptions. >>> >>> Thanks, >>> Masayoshi >>> >>> On 8/5/2009 11:03 AM, Martin Buchholz wrote: >>> >>>> >>>> Hi i18n team, >>>> >>>> FYI: >>>> >>>> I am intending to commit these changes to java.lang.Character >>>> >>>> http://cr.openjdk.java.net/~martin/webrevs/openjdk7/isSurrogate/ >>>> http://cr.openjdk.java.net/~martin/webrevs/openjdk7/isSurrogate2/ >>>> (follow-on change) >>>> >>>> as soon as I have CCC approval. >>>> >>>> Martin >>>> >>>> > >
