Improve docs for trimIndent/trimMargin.

#KT-9786

libraries/stdlib/src/kotlin/text/Indent.kt

@@ -5,12 +5,11 @@ package kotlin.text
 
 /**
  * Trims leading whitespace characters followed by [marginPrefix] from every line of a source string and removes
- * first and last lines if they are blank (notice difference blank vs empty). Doesn't affect line if it doesn't contain
- * [marginPrefix] except first and last blank lines
+ * first and last lines if they are blank (notice difference blank vs empty).
  *
- * Do not preserves original line endings
+ * Doesn't affect line if it doesn't contain [marginPrefix] except first and last blank lines.
  *
- * [marginPrefix] should be non-blank string
+ * Doesn't preserve original line endings.
  *
  * Example
  * ```kotlin
@@ -19,19 +18,18 @@ package kotlin.text
  *                             |456""".trimMargin())
  * ```
  *
- * @param marginPrefix characters to be used as a margin delimiter. Default is `|` (pipe character)
- * @return the trimmed String
- * @see kotlin.isWhitespace
- * @since M13
+ * @param marginPrefix non-blank string, characters to be used as a margin delimiter. Default is `|` (pipe character).
+ * @return deindented String
+ * @see kotlin.text.isWhitespace
  */
 public fun String.trimMargin(marginPrefix: String = "|"): String =
     replaceIndentByMargin("", marginPrefix)
 
 /**
- * Detects indent by [marginPrefix] as it does [trimMargin] and replace it with [newIndent]
+ * Detects indent by [marginPrefix] as it does [trimMargin] and replace it with [newIndent].
  */
 public fun String.replaceIndentByMargin(newIndent: String = "", marginPrefix: String = "|"): String {
-    require(marginPrefix.isNotBlank()) { "marginPrefix should be non blank string but it is '$marginPrefix'" }
+    require(marginPrefix.isNotBlank()) { "marginPrefix must be non blank string." }
     val lines = lines()
 
     return lines.reindent(length + newIndent.length * lines.size, getIndentFunction(newIndent), { line ->
@@ -48,29 +46,29 @@ public fun String.replaceIndentByMargin(newIndent: String = "", marginPrefix: St
 /**
  * Detects a common minimal indent of all the input lines, removes it from every line and also removes first and last
  * lines if they are blank (notice difference blank vs empty).
+ *
  * Note that blank lines do not affect detected indent level.
+ *
  * Please keep in mind that if there are non-blank lines with no leading whitespace characters (no indent at all) then the
  * common indent is 0 so this function may do nothing so it is recommended to keep first line empty (will be dropped).
  *
- * Do not preserves original line endings
+ * Doesn't preserve original line endings.
  *
  * Example
  * ```kotlin
  * assertEquals("ABC\n123\n456", """
  *                             ABC
  *                             123
- *                             456""".trimMargin())
+ *                             456""".trimIndent())
  * ```
  *
  * @return deindented String
- * @see kotlin.isBlank
- * @since M13
+ * @see kotlin.text.isBlank
  */
 public fun String.trimIndent(): String = replaceIndent("")
 
 /**
- * Detects a common minimal indent like it does [trimIndent] and replaces it with the specified [newIndent]
- * @since M13
+ * Detects a common minimal indent like it does [trimIndent] and replaces it with the specified [newIndent].
  */
 public fun String.replaceIndent(newIndent: String = ""): String {
     val lines = lines()
@@ -84,7 +82,9 @@ public fun String.replaceIndent(newIndent: String = ""): String {
 }
 
 /**
- * Prepends [indent] to every line of the original string. Does not preserve original line endings
+ * Prepends [indent] to every line of the original string.
+ *
+ * Doesn't preserve original line endings.
  */
 public fun String.prependIndent(indent: String = "    "): String =
     lineSequence()