From 1fb4183bbb16a0d8cac98cd78175b8c94ab79400 Mon Sep 17 00:00:00 2001 From: Ilya Gorbunov Date: Wed, 27 May 2015 22:13:54 +0300 Subject: [PATCH] Prettify kdocs in stdlib, part 2. --- .../src/kotlin/properties/Delegation.kt | 6 +-- libraries/stdlib/src/kotlin/test/Test.kt | 38 +++++++++---------- libraries/stdlib/src/kotlin/test/TestJVM.kt | 4 +- libraries/stdlib/src/kotlin/text/Char.kt | 2 +- libraries/stdlib/src/kotlin/text/CharJVM.kt | 2 +- .../stdlib/src/kotlin/text/CharsetsJVM.kt | 12 +++--- .../stdlib/src/kotlin/text/StringBuilder.kt | 6 +-- libraries/stdlib/src/kotlin/text/Strings.kt | 14 +++---- .../stdlib/src/kotlin/text/StringsJVM.kt | 2 +- .../stdlib/src/kotlin/text/Typography.kt | 2 +- .../stdlib/src/kotlin/text/regex/Regex.kt | 2 +- .../stdlib/src/kotlin/text/regex/RegexJVM.kt | 2 +- libraries/stdlib/src/kotlin/util/Ordering.kt | 8 ++-- .../stdlib/src/kotlin/util/Preconditions.kt | 2 +- .../stdlib/src/kotlin/util/StandardJVM.kt | 2 +- libraries/stdlib/src/kotlin/util/Tuples.kt | 20 +++++----- 16 files changed, 62 insertions(+), 62 deletions(-) diff --git a/libraries/stdlib/src/kotlin/properties/Delegation.kt b/libraries/stdlib/src/kotlin/properties/Delegation.kt index 5a0191cc585..90e03b515c1 100644 --- a/libraries/stdlib/src/kotlin/properties/Delegation.kt +++ b/libraries/stdlib/src/kotlin/properties/Delegation.kt @@ -47,7 +47,7 @@ public interface ReadWriteProperty { */ 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(initial: T, onChange: (desc: PropertyMetadata, oldValue: T, newValue: T) -> Boolean): ReadWriteProperty { return ObservableProperty(initial, onChange) @@ -133,7 +133,7 @@ private class NotNullVar() : ReadWriteProperty { * 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( initialValue: T, private val onChange: (name: PropertyMetadata, oldValue: T, newValue: T) -> Boolean diff --git a/libraries/stdlib/src/kotlin/test/Test.kt b/libraries/stdlib/src/kotlin/test/Test.kt index d0f4e757ea6..b1357c618c1 100644 --- a/libraries/stdlib/src/kotlin/test/Test.kt +++ b/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 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 assertNotNull(actual: T?, message: String = "", block: (T) -> R) { asserter.assertNotNull(message, actual) if (actual != null) { @@ -54,28 +54,28 @@ public inline fun 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 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 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. */ diff --git a/libraries/stdlib/src/kotlin/test/TestJVM.kt b/libraries/stdlib/src/kotlin/test/TestJVM.kt index c9209e66407..c29281eea88 100644 --- a/libraries/stdlib/src/kotlin/test/TestJVM.kt +++ b/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 failsWith(exceptionClass: Class, block: ()-> Any): T { try { block() @@ -17,7 +17,7 @@ public fun failsWith(exceptionClass: Class, 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) { diff --git a/libraries/stdlib/src/kotlin/text/Char.kt b/libraries/stdlib/src/kotlin/text/Char.kt index 98c563aca8e..48353db0b5f 100644 --- a/libraries/stdlib/src/kotlin/text/Char.kt +++ b/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 diff --git a/libraries/stdlib/src/kotlin/text/CharJVM.kt b/libraries/stdlib/src/kotlin/text/CharJVM.kt index 076aaed7b44..60d6c495287 100644 --- a/libraries/stdlib/src/kotlin/text/CharJVM.kt +++ b/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()) diff --git a/libraries/stdlib/src/kotlin/text/CharsetsJVM.kt b/libraries/stdlib/src/kotlin/text/CharsetsJVM.kt index e96ecfe0207..7862758b40c 100644 --- a/libraries/stdlib/src/kotlin/text/CharsetsJVM.kt +++ b/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") diff --git a/libraries/stdlib/src/kotlin/text/StringBuilder.kt b/libraries/stdlib/src/kotlin/text/StringBuilder.kt index de8fffe04f6..5812196903d 100644 --- a/libraries/stdlib/src/kotlin/text/StringBuilder.kt +++ b/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.append(vararg value: CharSequence?): T { for (item in value) @@ -19,7 +19,7 @@ public fun 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) diff --git a/libraries/stdlib/src/kotlin/text/Strings.kt b/libraries/stdlib/src/kotlin/text/Strings.kt index 7aa85d9892a..cda0138110e 100644 --- a/libraries/stdlib/src/kotlin/text/Strings.kt +++ b/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 diff --git a/libraries/stdlib/src/kotlin/text/StringsJVM.kt b/libraries/stdlib/src/kotlin/text/StringsJVM.kt index b7e4532f4f5..9dd5e9d0b84 100644 --- a/libraries/stdlib/src/kotlin/text/StringsJVM.kt +++ b/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 { diff --git a/libraries/stdlib/src/kotlin/text/Typography.kt b/libraries/stdlib/src/kotlin/text/Typography.kt index b7b532326c5..e4aaf0f4443 100644 --- a/libraries/stdlib/src/kotlin/text/Typography.kt +++ b/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 " */ diff --git a/libraries/stdlib/src/kotlin/text/regex/Regex.kt b/libraries/stdlib/src/kotlin/text/regex/Regex.kt index 34329761b9f..7e9259ea565 100644 --- a/libraries/stdlib/src/kotlin/text/regex/Regex.kt +++ b/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 { - /** 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. * diff --git a/libraries/stdlib/src/kotlin/text/regex/RegexJVM.kt b/libraries/stdlib/src/kotlin/text/regex/RegexJVM.kt index b7eaa89cc03..57784c56d2f 100644 --- a/libraries/stdlib/src/kotlin/text/regex/RegexJVM.kt +++ b/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) diff --git a/libraries/stdlib/src/kotlin/util/Ordering.kt b/libraries/stdlib/src/kotlin/util/Ordering.kt index be7409162b5..2cfedd6ebc3 100644 --- a/libraries/stdlib/src/kotlin/util/Ordering.kt +++ b/libraries/stdlib/src/kotlin/util/Ordering.kt @@ -68,7 +68,7 @@ deprecated("Use compareBy() instead", ReplaceWith("compareBy(*functions)")) public fun comparator(vararg functions: (T) -> Comparable<*>?): Comparator = 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 compareBy(inlineOptions(InlineOption.ONLY_LOCAL_RETURN) comparable: (T) -> Comparable<*>): Comparator { return object : Comparator { @@ -77,7 +77,7 @@ inline public fun 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 compareByDescending(inlineOptions(InlineOption.ONLY_LOCAL_RETURN) comparable: (T) -> Comparable<*>): Comparator { return object : Comparator { @@ -87,7 +87,7 @@ inline public fun 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 Comparator.thenBy(inlineOptions(InlineOption.ONLY_LOCAL_RETURN) comparable: (T) -> Comparable<*>): Comparator { return object : Comparator { @@ -100,7 +100,7 @@ inline public fun Comparator.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 Comparator.thenByDescending(inlineOptions(InlineOption.ONLY_LOCAL_RETURN) comparable: (T) -> Comparable<*>): Comparator { return object : Comparator { diff --git a/libraries/stdlib/src/kotlin/util/Preconditions.kt b/libraries/stdlib/src/kotlin/util/Preconditions.kt index 340a593bb12..626c97498fc 100644 --- a/libraries/stdlib/src/kotlin/util/Preconditions.kt +++ b/libraries/stdlib/src/kotlin/util/Preconditions.kt @@ -94,7 +94,7 @@ public fun 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 */ diff --git a/libraries/stdlib/src/kotlin/util/StandardJVM.kt b/libraries/stdlib/src/kotlin/util/StandardJVM.kt index 77b51232f0d..5d14d3a317b 100644 --- a/libraries/stdlib/src/kotlin/util/StandardJVM.kt +++ b/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 diff --git a/libraries/stdlib/src/kotlin/util/Tuples.kt b/libraries/stdlib/src/kotlin/util/Tuples.kt index 6ce04fcfbca..6d89eab63ea 100644 --- a/libraries/stdlib/src/kotlin/util/Tuples.kt +++ b/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( @@ -41,12 +41,12 @@ public fun Pair.toList(): List = 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( public val first: A,