Unify and improve Regex docs

libraries/stdlib/jvm/src/kotlin/text/regex/Regex.kt

@@ -79,9 +79,10 @@ public actual enum class RegexOption(override val value: Int, override val mask:
 public actual data class MatchGroup(public actual val value: String, public val range: IntRange)
 
 /**
- * Represents an immutable regular expression.
+ * Represents a compiled regular expression.
+ * Provides functions to match strings in text with a pattern, replace the found occurrences and split text around matches.
  *
- * For pattern syntax reference see [Pattern]
+ * For pattern syntax reference see [Pattern].
  */
 public actual class Regex
 @PublishedApi
@@ -206,7 +207,12 @@ internal constructor(private val nativePattern: Pattern) : Serializable {
         return result
     }
 
-    /** Returns the string representation of this regular expression, namely the [pattern] of this regular expression. */
+    /**
+     * Returns the string representation of this regular expression, namely the [pattern] of this regular expression.
+     *
+     * Note that another regular expression constructed from the same pattern string may have different [options]
+     * and may match strings differently.
+     */
     public override fun toString(): String = nativePattern.toString()
 
     /**
@@ -227,13 +233,22 @@ internal constructor(private val nativePattern: Pattern) : Serializable {
     }
 
     actual companion object {
-        /** Returns a literal regex for the specified [literal] string. */
+        /**
+         * Returns a regular expression that matches the specified [literal] string literally.
+         * No characters of that string will have special meaning when searching for an occurrence of the regular expression.
+         */
         public actual fun fromLiteral(literal: String): Regex = literal.toRegex(RegexOption.LITERAL)
 
-        /** Returns a literal pattern for the specified [literal] string. */
+        /**
+         * Returns a regular expression pattern string that matches the specified [literal] string literally.
+         * No characters of that string will have special meaning when searching for an occurrence of the regular expression.
+         */
         public actual fun escape(literal: String): String = Pattern.quote(literal)
 
-        /** Returns a literal replacement expression for the specified [literal] string. */
+        /**
+         * Returns a literal replacement expression for the specified [literal] string.
+         * No characters of that string will have special meaning when it is used as a replacement string in [Regex.replace] function.
+         */
         public actual fun escapeReplacement(literal: String): String = Matcher.quoteReplacement(literal)
 
         private fun ensureUnicodeCase(flags: Int) = if (flags and Pattern.CASE_INSENSITIVE != 0) flags or Pattern.UNICODE_CASE else flags