<div dir="ltr">Hello,<br><div><br></div><div>During a discussion about the deprecation of String.toLowerCase(), String.toUpperCase [1], it occurred to me that the current Note in the API documentation could be more specific when talking about locales.</div><div><br></div><div>Before going ahead and suggesting a PR/CSR, I'd like to socialize the idea that we could improve the Notes in these somewhat suspicious methods.</div><div><br></div><div>The current notes look like this:</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Note: This method is locale sensitive, and may produce unexpected<br>results if used for strings that are intended to be interpreted locale<br>independently.</blockquote><div><br></div><div>Sensitive to which locale? Independently of which locale?</div><div><br></div><div>It then goes on to say:</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">To obtain correct results for locale insensitive strings, use toUpperCase(Locale.ROOT)</blockquote><div><br></div><div>What are "locale insensitive strings"?</div><div><br></div><div>Here is an attempt to be more specific:</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Note: This method is sensitive to the default locale for this instance<br>of the Java Virtual Machine. It  may produce unexpected<br>results if used for strings that are intended to be interpreted<br> independent of the default locale.</blockquote><div><br></div><div>For the last part, I suggest using "language/country neutral results" instead of "locale insensitive strings":</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">To obtain language/country neutral results, use toLowerCase(Locale.ROOT)</blockquote><div><br></div><div>Any thoughts?</div><div><br></div><div>Thanks,</div><div>Eirik.</div><div>[1] <a href="https://github.com/openjdk/jdk/pull/13434#issuecomment-1505832883">https://github.com/openjdk/jdk/pull/13434#issuecomment-1505832883</a></div></div>