WTF: Add comments and tests for Unicode aware case-insensitive string operations.

third_party/WebKit/Source/wtf/text/AtomicString.h

Index: third_party/WebKit/Source/wtf/text/AtomicString.h
diff --git a/third_party/WebKit/Source/wtf/text/AtomicString.h b/third_party/WebKit/Source/wtf/text/AtomicString.h
index 4099cd8e352735faf3c87f12c67f37bdee36c018..9fc2eb654dd113d4e645d2047b90b72d19d190b4 100644
--- a/third_party/WebKit/Source/wtf/text/AtomicString.h
+++ b/third_party/WebKit/Source/wtf/text/AtomicString.h
@@ -104,7 +104,9 @@ class WTF_EXPORT AtomicString {
     return m_string.find(value, start, caseSensitivity);
   }
 
-  // Unicode aware case insensitive string matching.
+  // Unicode aware case insensitive string matching. Non-ASCII characters might
+  // match to ASCII characters. This function is rarely used to implement web
+  // platform features.
   size_t findIgnoringCase(const StringView& value, unsigned start = 0) const {
     return m_string.findIgnoringCase(value, start);
   }
@@ -144,10 +146,17 @@ class WTF_EXPORT AtomicString {
   }
   bool endsWith(UChar character) const { return m_string.endsWith(character); }
 
+  // Returns a lowercase/uppercase version of the string. These functions might
+  // convert non-ASCII characters to ASCII characters. For example, lower() for
+  // U+212A is 'k', upper() for U+017F is 'S'.
+  // These functions are rarely used to implement web platform features.
   AtomicString lower() const;
-  AtomicString lowerASCII() const;
   AtomicString upper() const { return AtomicString(impl()->upper()); }
 
+  // Returns a lowercase version of the string. This function converts only
+  // upper-case ASCII characters.
+  AtomicString lowerASCII() const;
+
   int toInt(bool* ok = 0) const { return m_string.toInt(ok); }
   double toDouble(bool* ok = 0) const { return m_string.toDouble(ok); }
   float toFloat(bool* ok = 0) const { return m_string.toFloat(ok); }