Prettify kdocs in stdlib, part 2.

libraries/stdlib/src/kotlin/properties/Delegation.kt

@@ -47,7 +47,7 @@ public interface ReadWriteProperty<in R, T> {
  */
 public object Delegates {
     /**
-     * Returns a property delegate for a read/write property with a non-null value that is initialized not during
+     * Returns a property delegate for a read/write property with a non-`null` value that is initialized not during
      * object construction time but at a later time. Trying to read the property before the initial value has been
      * assigned results in an exception.
      */
@@ -87,7 +87,7 @@ public object Delegates {
      * allowing the callback to veto the modification.
      * @param initial the initial value of the property.
      * @param onChange the callback which is called when a change to the property value is attempted. The new value
-    *                  is saved if the callback returns true and discarded if the callback returns false.
+    *                  is saved if the callback returns `true` and discarded if the callback returns `false`.
      */
     public fun vetoable<T>(initial: T, onChange: (desc: PropertyMetadata, oldValue: T, newValue: T) -> Boolean): ReadWriteProperty<Any?, T> {
         return ObservableProperty<T>(initial, onChange)
@@ -133,7 +133,7 @@ private class NotNullVar<T: Any>() : ReadWriteProperty<Any?, T> {
  * Implements a property delegate for a read/write property that calls a specified callback function when changed.
  * @param initialValue the initial value of the property.
  * @param onChange the callback which is called when a change to the property value is attempted. The new value
-*                  is saved if the callback returns true and discarded if the callback returns false.
+*                  is saved if the callback returns `true` and discarded if the callback returns `false`.
  */
 public class ObservableProperty<T>(
         initialValue: T, private val onChange: (name: PropertyMetadata, oldValue: T, newValue: T) -> Boolean

libraries/stdlib/src/kotlin/test/Test.kt

@@ -1,52 +1,52 @@
 /**
- * A number of helper methods for writing unit tests
+ * A number of helper methods for writing unit tests.
  */
 package kotlin.test
 
-/** Asserts that the given block returns true */
+/** Asserts that the given [block] returns `true`. */
 public inline fun assertTrue(message: String, block: () -> Boolean) {
     val actual = block()
     asserter.assertTrue(message, actual)
 }
 
-/** Asserts that the given block returns true */
+/** Asserts that the given [block] returns `true`. */
 public inline fun assertTrue(block: () -> Boolean): Unit = assertTrue("expected true", block)
 
-/** Asserts that the given block returns false */
+/** Asserts that the given [block] returns `false`. */
 public inline fun assertNot(message: String, block: () -> Boolean) {
     assertTrue(message) { !block() }
 }
 
-/** Asserts that the given block returns false */
+/** Asserts that the given [block] returns `false`. */
 public fun assertNot(block: () -> Boolean): Unit = assertNot("expected false", block)
 
-/** Asserts that the expression is true with an optional message */
+/** Asserts that the expression is `true` with an optional [message]. */
 public fun assertTrue(actual: Boolean, message: String = "") {
     return assertEquals(true, actual, message)
 }
 
-/** Asserts that the expression is false with an optional message */
+/** Asserts that the expression is `false` with an optional [message]. */
 public fun assertFalse(actual: Boolean, message: String = "") {
     return assertEquals(false, actual, message)
 }
 
-/** Asserts that the expected value is equal to the actual value, with an optional message */
+/** Asserts that the [expected] value is equal to the [actual] value, with an optional [message]. */
 public fun assertEquals(expected: Any?, actual: Any?, message: String = "") {
     asserter.assertEquals(message, expected, actual)
 }
 
-/** Asserts that the actual value is not equal to the illegal value, with an optional message */
+/** Asserts that the [actual] value is not equal to the illegal value, with an optional [message]. */
 public fun assertNotEquals(illegal: Any?, actual: Any?, message: String = "") {
     asserter.assertNotEquals(message, illegal, actual)
 }
 
-/** Asserts that the expression is not null, with an optional message */
+/** Asserts that the [actual] value is not `null`, with an optional [message]. */
 public fun <T : Any> assertNotNull(actual: T?, message: String = ""): T {
     asserter.assertNotNull(message, actual)
     return actual!!
 }
 
-/** Asserts that the expression is not null, with an optional message and a function block to process the not-null value */
+/** Asserts that the [actual] value is not `null`, with an optional [message] and a function [block] to process the not-null value. */
 public inline fun <T : Any, R> assertNotNull(actual: T?, message: String = "", block: (T) -> R) {
     asserter.assertNotNull(message, actual)
     if (actual != null) {
@@ -54,28 +54,28 @@ public inline fun <T : Any, R> assertNotNull(actual: T?, message: String = "", b
     }
 }
 
-/** Asserts that the expression is null, with an optional message */
+/** Asserts that the [actual] value is `null`, with an optional [message]. */
 public fun assertNull(actual: Any?, message: String = "") {
     asserter.assertNull(message, actual)
 }
 
-/** Marks a test as having failed if this point in the execution path is reached, with an optional message */
+/** Marks a test as having failed if this point in the execution path is reached, with an optional [message]. */
 public fun fail(message: String = "") {
     asserter.fail(message)
 }
 
-/** Asserts that given function block returns the given expected value */
+/** Asserts that given function [block] returns the given [expected] value. */
 public inline fun <T> expect(expected: T, block: () -> T) {
     expect(expected, "expected " + expected, block)
 }
 
-/** Asserts that given function block returns the given expected value and use the given message if it fails */
+/** Asserts that given function [block] returns the given [expected] value and use the given [message] if it fails. */
 public inline fun <T> expect(expected: T, message: String, block: () -> T) {
     val actual = block()
     assertEquals(expected, actual, message)
 }
 
-/** Asserts that given function block fails by throwing an exception */
+/** Asserts that given function [block] fails by throwing an exception. */
 public fun fails(block: () -> Unit): Throwable? {
     var thrown: Throwable? = null
     try {
@@ -94,7 +94,7 @@ public fun fails(block: () -> Unit): Throwable? {
  */
 public interface Asserter {
     /**
-     * Asserts that the specified value is true.
+     * Asserts that the specified value is `true`.
      *
      * @param message the message to report if the assertion fails.
      */
@@ -115,14 +115,14 @@ public interface Asserter {
     public fun assertNotEquals(message: String, illegal: Any?, actual: Any?): Unit
 
     /**
-     * Asserts that the specified value is not null.
+     * Asserts that the specified value is not `null`.
      *
      * @param message the message to report if the assertion fails.
      */
     public fun assertNotNull(message: String, actual: Any?): Unit
 
     /**
-     * Asserts that the specified value is null.
+     * Asserts that the specified value is `null`.
      *
      * @param message the message to report if the assertion fails.
      */

libraries/stdlib/src/kotlin/test/TestJVM.kt

@@ -2,7 +2,7 @@ package kotlin.test
 
 import java.util.ServiceLoader
 
-/** Asserts that a block fails with a specific exception being thrown */
+/** Asserts that a [block] fails with a specific exception being thrown */
 public fun <T: Throwable> failsWith(exceptionClass: Class<T>, block: ()-> Any): T {
     try {
         block()
@@ -17,7 +17,7 @@ public fun <T: Throwable> failsWith(exceptionClass: Class<T>, block: ()-> Any):
 }
 
 /**
- * Comments out a block of test code until it is implemented while keeping a link to the code
+ * Comments out a [block] of test code until it is implemented while keeping a link to the code
  * to implement in your unit test output
  */
 public inline fun todo(block: ()-> Any) {

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

@@ -26,7 +26,7 @@ public fun Char.plus(string: String) : String = this.toString() + string
  *
  * @param ignoreCase `true` to ignore character case when comparing characters. By default `false`.
  *
- * Two characters are considered the same ignoring case if at least one of the following is true:
+ * Two characters are considered the same ignoring case if at least one of the following is `true`:
  *   - The two characters are the same (as compared by the == operator)
  *   - Applying the method [toUpperCase] to each character produces the same result
  *   - Applying the method [toLowerCase] to each character produces the same result

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

@@ -114,6 +114,6 @@ public fun Char.directionality(): CharDirectionality = CharDirectionality.valueO
 
 // TODO Provide name for JVM7+
 ///**
-// * Returns the Unicode name of this character, or null if the code point of this character is unassigned.
+// * Returns the Unicode name of this character, or `null` if the code point of this character is unassigned.
 // */
 //public fun Char.name(): String? = Character.getName(this.toInt())

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

@@ -10,39 +10,39 @@ import kotlin.platform.*
  */
 public object Charsets {
     /**
-     * Eight-bit UCS Transformation Format
+     * Eight-bit UCS Transformation Format.
      */
     platformStatic
     public val UTF_8: Charset = Charset.forName("UTF-8")
 
     /**
      * Sixteen-bit UCS Transformation Format, byte order identified by an
-     * optional byte-order mark
+     * optional byte-order mark.
      */
     platformStatic
     public val UTF_16: Charset = Charset.forName("UTF-16")
 
     /**
-     * Sixteen-bit UCS Transformation Format, big-endian byte order
+     * Sixteen-bit UCS Transformation Format, big-endian byte order.
      */
     platformStatic
     public val UTF_16BE: Charset = Charset.forName("UTF-16BE")
 
     /**
-     * Sixteen-bit UCS Transformation Format, little-endian byte order
+     * Sixteen-bit UCS Transformation Format, little-endian byte order.
      */
     platformStatic
     public val UTF_16LE: Charset = Charset.forName("UTF-16LE")
 
     /**
      * Seven-bit ASCII, a.k.a. ISO646-US, a.k.a. the Basic Latin block of the
-     * Unicode character set
+     * Unicode character set.
      */
     platformStatic
     public val US_ASCII: Charset = Charset.forName("US-ASCII")
 
     /**
-     * ISO Latin Alphabet No. 1, a.k.a. ISO-LATIN-1
+     * ISO Latin Alphabet No. 1, a.k.a. ISO-LATIN-1.
      */
     platformStatic
     public val ISO_8859_1: Charset = Charset.forName("ISO-8859-1")

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

@@ -10,7 +10,7 @@ public inline fun StringBuilder(body: StringBuilder.() -> Unit): StringBuilder {
 }
 
 /**
- * Appends all arguments to the given Appendable
+ * Appends all arguments to the given Appendable.
  */
 public fun <T : Appendable> T.append(vararg value: CharSequence?): T {
     for (item in value)
@@ -19,7 +19,7 @@ public fun <T : Appendable> T.append(vararg value: CharSequence?): T {
 }
 
 /**
- * Appends all arguments to the given StringBuilder
+ * Appends all arguments to the given StringBuilder.
  */
 public fun StringBuilder.append(vararg value: String?): StringBuilder {
     for (item in value)
@@ -28,7 +28,7 @@ public fun StringBuilder.append(vararg value: String?): StringBuilder {
 }
 
 /**
- * Appends all arguments to the given StringBuilder
+ * Appends all arguments to the given StringBuilder.
  */
 public fun StringBuilder.append(vararg value: Any?): StringBuilder {
     for (item in value)

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

@@ -148,13 +148,13 @@ public fun String.padEnd(length: Int, padChar: Char = ' '): String {
     return sb.toString()
 }
 
-/** Returns true if the string is not null and not empty */
+/** Returns `true` if the string is not `null` and not empty */
 deprecated("Use !isNullOrEmpty() or isNullOrEmpty().not() for nullable strings.")
 platformName("isNotEmptyNullable")
 public fun String?.isNotEmpty(): Boolean = this != null && this.length() > 0
 
 /**
- * Returns `true` if this nullable string is either null or empty.
+ * Returns `true` if this nullable string is either `null` or empty.
  */
 public fun String?.isNullOrEmpty(): Boolean = this == null || this.length() == 0
 
@@ -178,12 +178,12 @@ public fun String.isNotEmpty(): Boolean = length() > 0
 public fun String.isNotBlank(): Boolean = !isBlank()
 
 /**
- * Returns `true` if this nullable string is either null or empty or consists solely of whitespace characters.
+ * Returns `true` if this nullable string is either `null` or empty or consists solely of whitespace characters.
  */
 public fun String?.isNullOrBlank(): Boolean = this == null || this.isBlank()
 
 /**
- * Iterator for characters of given CharSequence
+ * Iterator for characters of given CharSequence.
  */
 public fun CharSequence.iterator(): CharIterator = object : CharIterator() {
     private var index = 0
@@ -193,7 +193,7 @@ public fun CharSequence.iterator(): CharIterator = object : CharIterator() {
     public override fun hasNext(): Boolean = index < length
 }
 
-/** Returns the string if it is not null, or the empty string otherwise. */
+/** Returns the string if it is not `null`, or the empty string otherwise. */
 public fun String?.orEmpty(): String = this ?: ""
 
 /**
@@ -203,7 +203,7 @@ public val String.indices: IntRange
     get() = 0..length() - 1
 
 /**
- * Returns the index of the last character in the String or -1 if the String is empty
+ * Returns the index of the last character in the String or -1 if the String is empty.
  */
 public val String.lastIndex: Int
     get() = this.length() - 1
@@ -218,7 +218,7 @@ public val String.lastIndex: Int
 public fun CharSequence.get(index: Int): Char = this.charAt(index)
 
 /**
- * Returns `true` if this CharSequence has Unicode surrogate pair at the specified [index]
+ * Returns `true` if this CharSequence has Unicode surrogate pair at the specified [index].
  */
 public fun CharSequence.hasSurrogatePairAt(index: Int): Boolean {
     return index in 0..length() - 2

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

@@ -484,7 +484,7 @@ public fun String.decapitalize(): String {
 
 /**
  * Repeats a given string [n] times.
- * @throws IllegalArgumentException when n < 0
+ * @throws [IllegalArgumentException] when n < 0.
  * @sample test.text.StringJVMTest.repeat
  */
 public fun String.repeat(n: Int): String {

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

@@ -1,7 +1,7 @@
 package kotlin
 
 /**
- * Defines names for Unicode symbols used in proper Typography
+ * Defines names for Unicode symbols used in proper Typography.
  */
 public object Typography {
     /** The character " */

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

@@ -19,7 +19,7 @@ package kotlin.text
 /** Represents a collection of captured groups in a single match. */
 public interface MatchGroupCollection : Collection<MatchGroup?> {
 
-    /** Returns a group with the specified [index]
+    /** Returns a group with the specified [index].
      *
      * @return An instance of [MatchGroup] if the group with the specified [index] was matched or `null` otherwise.
      *

libraries/stdlib/src/kotlin/text/regex/RegexJVM.kt

@@ -79,7 +79,7 @@ public enum class RegexOption(override val value: Int, override val mask: Int =
  * @param value The value of captured group.
  * @param range The range of indices in the input string where group was captured.
  *
- * The [range] property is available on JVM only
+ * The [range] property is available on JVM only.
  */
 public data class MatchGroup(public val value: String, public val range: IntRange)
 

libraries/stdlib/src/kotlin/util/Ordering.kt

@@ -68,7 +68,7 @@ deprecated("Use compareBy() instead", ReplaceWith("compareBy(*functions)"))
 public fun <T> comparator(vararg functions: (T) -> Comparable<*>?): Comparator<T> = compareBy(*functions)
 
 /**
- * Creates a comparator using the function to transform value to a [Comparable] instance for comparison
+ * Creates a comparator using the function to transform value to a [Comparable] instance for comparison.
  */
 inline public fun <T> compareBy(inlineOptions(InlineOption.ONLY_LOCAL_RETURN) comparable: (T) -> Comparable<*>): Comparator<T> {
     return object : Comparator<T> {
@@ -77,7 +77,7 @@ inline public fun <T> compareBy(inlineOptions(InlineOption.ONLY_LOCAL_RETURN) co
 }
 
 /**
- * Creates a descending comparator using the function to transform value to a [Comparable] instance for comparison
+ * Creates a descending comparator using the function to transform value to a [Comparable] instance for comparison.
  */
 inline public fun <T> compareByDescending(inlineOptions(InlineOption.ONLY_LOCAL_RETURN) comparable: (T) -> Comparable<*>): Comparator<T> {
     return object : Comparator<T> {
@@ -87,7 +87,7 @@ inline public fun <T> compareByDescending(inlineOptions(InlineOption.ONLY_LOCAL_
 
 /**
  * Creates a comparator using the primary comparator and
- * the function to transform value to a [Comparable] instance for comparison
+ * the function to transform value to a [Comparable] instance for comparison.
  */
 inline public fun <T> Comparator<T>.thenBy(inlineOptions(InlineOption.ONLY_LOCAL_RETURN) comparable: (T) -> Comparable<*>): Comparator<T> {
     return object : Comparator<T> {
@@ -100,7 +100,7 @@ inline public fun <T> Comparator<T>.thenBy(inlineOptions(InlineOption.ONLY_LOCAL
 
 /**
  * Creates a descending comparator using the primary comparator and
- * the function to transform value to a [Comparable] instance for comparison
+ * the function to transform value to a [Comparable] instance for comparison.
  */
 inline public fun <T> Comparator<T>.thenByDescending(inlineOptions(InlineOption.ONLY_LOCAL_RETURN) comparable: (T) -> Comparable<*>): Comparator<T> {
     return object : Comparator<T> {

libraries/stdlib/src/kotlin/util/Preconditions.kt

@@ -94,7 +94,7 @@ public fun <T:Any> checkNotNull(value: T?, message: Any = "Required value was nu
 }
 
 /**
- * Throws an [IllegalStateException] with the given [message]
+ * Throws an [IllegalStateException] with the given [message].
  *
  * @sample test.collections.PreconditionsTest.error
  */

libraries/stdlib/src/kotlin/util/StandardJVM.kt

@@ -12,7 +12,7 @@ public fun Throwable.printStackTrace(writer: PrintWriter): Unit {
 }
 
 /**
- * Allows a stack trace to be printed from Kotlin's [Throwable]
+ * Allows a stack trace to be printed from Kotlin's [Throwable].
  */
 public fun Throwable.printStackTrace(stream: PrintStream): Unit {
     val jlt = this as java.lang.Throwable

libraries/stdlib/src/kotlin/util/Tuples.kt

@@ -11,10 +11,10 @@ import java.io.Serializable
  * An example of decomposing it into values:
  * @sample test.tuples.PairTest.pairMultiAssignment
  *
- * @param A type of the first value
- * @param B type of the second value
- * @property first First value
- * @property second Second value
+ * @param A type of the first value.
+ * @param B type of the second value.
+ * @property first First value.
+ * @property second Second value.
  * @constructor Creates a new instance of Pair.
  */
 public data class Pair<out A, out B>(
@@ -41,12 +41,12 @@ public fun <T> Pair<T, T>.toList(): List<T> = listOf(first, second)
  * An example of decomposing it into values:
  * @sample test.tuples.TripleTest.tripleMultiAssignment
  *
- * @param A type of the first value
- * @param B type of the second value
- * @param C type of the third value
- * @property first First value
- * @property second Second value
- * @property third Third value
+ * @param A type of the first value.
+ * @param B type of the second value.
+ * @param C type of the third value.
+ * @property first First value.
+ * @property second Second value.
+ * @property third Third value.
  */
 public data class Triple<out A, out B, out C>(
         public val first: A,