capitalize/decapitalize: improve docs, add one test

libraries/stdlib/jvm/src/kotlin/text/StringsJVM.kt

@@ -568,9 +568,9 @@ public actual fun String.capitalize(): String {
 }
 
 /**
- * Returns a copy of this string having its first letter uppercased preferring [Character.toTitleCase] (if different from
+ * Returns a copy of this string having its first letter titlecased preferring [Char.toTitleCase] (if different from
- * [Character.toUpperCase]) or by [String.toUpperCase] using [locale], or the original string, if it's empty or already
+ * [Char.toUpperCase]) or by [String.toUpperCase] using the specified [locale], or the original string,
- * starts with an upper case letter.
+ * if it's empty or already starts with an upper case letter.
  */
 @SinceKotlin("1.3")
 @ExperimentalStdlibApi
@@ -603,8 +603,8 @@ public actual fun String.decapitalize(): String {
 }
 
 /**
- * Returns a copy of this string having its first letter lowercased using [locale], or the original string,
+ * Returns a copy of this string having its first letter lowercased using the specified [locale],
- * if it's empty or already starts with a lower case letter.
+ * or the original string, if it's empty or already starts with a lower case letter.
  */
 @SinceKotlin("1.3")
 @ExperimentalStdlibApi

libraries/stdlib/jvm/test/text/StringJVMTest.kt

@@ -68,7 +68,6 @@ class StringJVMTest {
         assertEquals("UTF-32BE", Charsets.UTF_32BE.name())
     }
 
-    @ExperimentalStdlibApi
     @Test fun capitalizeLocale() {
         assertEquals("ABC", "ABC".capitalize(Locale.US))
         assertEquals("Abc", "Abc".capitalize(Locale.US))
@@ -83,9 +82,9 @@ class StringJVMTest {
 
         // Case mapping where title case is different than uppercase and so Character.toTitleCase is preferred.
         assertEquals("Dzdzdz", "dzdzdz".capitalize(Locale.US))
+        assertEquals("DZDZDZ", "DZDZDZ".capitalize(Locale.US))
     }
 
-    @ExperimentalStdlibApi
     @Test fun decapitalizeLocale() {
         assertEquals("aBC", "ABC".decapitalize(Locale.US))
         assertEquals("abc", "Abc".decapitalize(Locale.US))