Prettify kdocs in stdlib, part 1.

libraries/stdlib/src/kotlin/collections/ArraysJVM.kt

@@ -87,6 +87,6 @@ public inline fun <reified T> Collection<T>.toTypedArray(): Array<T> {
     return thisCollection.toArray(arrayOfNulls<T>(thisCollection.size())) as Array<T>
 }
 
-/** Returns the array if it's not null, or an empty array otherwise. */
+/** Returns the array if it's not `null`, or an empty array otherwise. */
 public inline fun <reified T> Array<out T>?.orEmpty(): Array<out T> = this ?: arrayOf<T>()
 

libraries/stdlib/src/kotlin/collections/JUtil.kt

@@ -99,23 +99,23 @@ public val Int.indices: IntRange
     get() = 0..this - 1
 
 /**
- * Returns the index of the last item in the list or -1 if the list is empty
+ * Returns the index of the last item in the list or -1 if the list is empty.
  *
  * @sample test.collections.ListSpecificTest.lastIndex
  */
 public val <T> List<T>.lastIndex: Int
     get() = this.size() - 1
 
-/** Returns true if the collection is not empty */
+/** Returns `true` if the collection is not empty. */
 public fun <T> Collection<T>.isNotEmpty(): Boolean = !isEmpty()
 
-/** Returns this Collection if it's not null and the empty list otherwise. */
+/** Returns this Collection if it's not `null` and the empty list otherwise. */
 public fun <T> Collection<T>?.orEmpty(): Collection<T> = this ?: emptyList()
 
-/** Returns this List if it's not null and the empty list otherwise. */
+/** Returns this List if it's not `null` and the empty list otherwise. */
 public fun <T> List<T>?.orEmpty(): List<T> = this ?: emptyList()
 
-/** Returns this Set if it's not null and the empty set otherwise. */
+/** Returns this Set if it's not `null` and the empty set otherwise. */
 public fun <T> Set<T>?.orEmpty(): Set<T> = this ?: emptySet()
 
 /**

libraries/stdlib/src/kotlin/collections/Maps.kt

@@ -79,11 +79,11 @@ private fun mapCapacity(expectedSize: Int): Int {
     return Int.MAX_VALUE // any large value
 }
 
-/** Returns true if this map is not empty. */
+/** Returns `true` if this map is not empty. */
 public fun <K, V> Map<K, V>.isNotEmpty(): Boolean = !isEmpty()
 
 /**
- * Returns the [Map] if its not null, or the empty [Map] otherwise.
+ * Returns the [Map] if its not `null`, or the empty [Map] otherwise.
  */
 public fun <K,V> Map<K,V>?.orEmpty() : Map<K,V> = this ?: emptyMap()
 
@@ -347,7 +347,7 @@ public fun <K, V> Iterable<Pair<K, V>>.toMap(): Map<K, V> {
 public fun <K, V> Map<K, V>.toLinkedMap(): MutableMap<K, V> = LinkedHashMap(this)
 
 /**
- * Creates a new read-only map by replacing or adding an entry to this map from a given key-value [pair]
+ * Creates a new read-only map by replacing or adding an entry to this map from a given key-value [pair].
  */
 public fun <K, V> Map<K, V>.plus(pair: Pair<K, V>): Map<K, V> {
     val newMap = this.toLinkedMap()
@@ -356,7 +356,7 @@ public fun <K, V> Map<K, V>.plus(pair: Pair<K, V>): Map<K, V> {
 }
 
 /**
- * Creates a new read-only map by replacing or adding entries to this map from a given collection of key-value [pairs]
+ * Creates a new read-only map by replacing or adding entries to this map from a given collection of key-value [pairs].
  */
 public fun <K, V> Map<K, V>.plus(pairs: Iterable<Pair<K, V>>): Map<K, V> {
     val newMap = this.toLinkedMap()
@@ -365,7 +365,7 @@ public fun <K, V> Map<K, V>.plus(pairs: Iterable<Pair<K, V>>): Map<K, V> {
 }
 
 /**
- * Creates a new read-only map by replacing or adding entries to this map from another [map]
+ * Creates a new read-only map by replacing or adding entries to this map from another [map].
  */
 public fun <K, V> Map<K, V>.plus(map: Map<K, V>): Map<K, V> {
     val newMap = this.toLinkedMap()
@@ -374,14 +374,14 @@ public fun <K, V> Map<K, V>.plus(map: Map<K, V>): Map<K, V> {
 }
 
 /**
- * Creates a new read-only map by removing a key from this map
+ * Creates a new read-only map by removing a [key] from this map.
  */
 public fun <K, V> Map<K, V>.minus(key: K): Map<K, V> {
     return this.filterKeys { key != it }
 }
 
 /**
- * Creates a new read-only map by removing a collection of keys from this map
+ * Creates a new read-only map by removing a collection of [keys] from this map.
  */
 public fun <K, V> Map<K, V>.minus(keys: Iterable<K>): Map<K, V> {
     val result = LinkedHashMap<K, V>()

libraries/stdlib/src/kotlin/collections/MapsJVM.kt

@@ -13,7 +13,7 @@ import java.util.Properties
 public fun <K, V> MutableMap<K, V>.set(key: K, value: V): V? = put(key, value)
 
 /**
- * Converts this [Map] to a [SortedMap] so iteration order will be in key order
+ * Converts this [Map] to a [SortedMap] so iteration order will be in key order.
  *
  * @sample test.collections.MapJVMTest.toSortedMap
  */
@@ -21,7 +21,7 @@ public fun <K : Comparable<K>, V> Map<K, V>.toSortedMap(): SortedMap<K, V> = Tre
 
 /**
  * Converts this [Map] to a [SortedMap] using the given [comparator] so that iteration order will be in the order
- * defined by the comparator
+ * defined by the comparator.
  *
  * @sample test.collections.MapJVMTest.toSortedMapWithComparator
  */
@@ -51,7 +51,7 @@ public fun <K, V> sortedMapOf(vararg values: Pair<K, V>): SortedMap<K, V> {
 
 
 /**
- * Converts this [Map] to a [Properties] object
+ * Converts this [Map] to a [Properties] object.
  *
  * @sample test.collections.MapJVMTest.toProperties
  */

libraries/stdlib/src/kotlin/concurrent/Locks.kt

@@ -33,8 +33,8 @@ public inline fun <T> ReentrantReadWriteLock.read(action: () -> T): T {
 
 /**
  * Executes the given [action] under the write lock of this lock.
- * The method does upgrade from read to write lock if needed
- * If such write has been initiated by checking some condition, the condition must be rechecked inside the action to avoid possible races
+ * The method does upgrade from read to write lock if needed.
+ * If such write has been initiated by checking some condition, the condition must be rechecked inside the action to avoid possible races.
  * @return the return value of the action.
  */
 public inline fun <T> ReentrantReadWriteLock.write(action: () -> T): T {

libraries/stdlib/src/kotlin/concurrent/Thread.kt

@@ -52,7 +52,7 @@ public var Thread.contextClassLoader: ClassLoader?
     }
 
 /**
- * Creates a thread that runs the specified [block] of code.\
+ * Creates a thread that runs the specified [block] of code.
  *
  * @param start if `true`, the thread is immediately started.
  * @param daemon if `true`, the thread is created as a daemon thread. The Java Virtual Machine exits when

libraries/stdlib/src/kotlin/concurrent/Timer.kt

@@ -70,7 +70,7 @@ public fun Timer.scheduleAtFixedRate(time: Date, period: Long, action: TimerTask
  * and the start of the next one.
  *
  * @param name the name to use for the thread which is running the timer.
- * @param daemon if true, the thread is started as a daemon thread (the VM will exit when only daemon threads are running)
+ * @param daemon if `true`, the thread is started as a daemon thread (the VM will exit when only daemon threads are running).
  */
 public fun timer(name: String? = null, daemon: Boolean = false, initialDelay: Long = 0.toLong(), period: Long, action: TimerTask.() -> Unit): Timer {
     val timer = if (name == null) Timer(daemon) else Timer(name, daemon)
@@ -83,7 +83,7 @@ public fun timer(name: String? = null, daemon: Boolean = false, initialDelay: Lo
  * and with the interval of [period] milliseconds between the end of the previous task and the start of the next one.
  *
  * @param name the name to use for the thread which is running the timer.
- * @param daemon if true, the thread is started as a daemon thread (the VM will exit when only daemon threads are running)
+ * @param daemon if `true`, the thread is started as a daemon thread (the VM will exit when only daemon threads are running).
  */
 public fun timer(name: String? = null, daemon: Boolean = false, startAt: Date, period: Long, action: TimerTask.() -> Unit): Timer {
     val timer = if (name == null) Timer(daemon) else Timer(name, daemon)
@@ -97,7 +97,7 @@ public fun timer(name: String? = null, daemon: Boolean = false, startAt: Date, p
  * and the start of the next one.
  *
  * @param name the name to use for the thread which is running the timer.
- * @param daemon if true, the thread is started as a daemon thread (the VM will exit when only daemon threads are running)
+ * @param daemon if `true`, the thread is started as a daemon thread (the VM will exit when only daemon threads are running).
  */
 public fun fixedRateTimer(name: String? = null, daemon: Boolean = false, initialDelay: Long = 0.toLong(), period: Long, action: TimerTask.() -> Unit): Timer {
     val timer = if (name == null) Timer(daemon) else Timer(name, daemon)
@@ -110,7 +110,7 @@ public fun fixedRateTimer(name: String? = null, daemon: Boolean = false, initial
  * and with the interval of [period] milliseconds between the start of the previous task and the start of the next one.
  *
  * @param name the name to use for the thread which is running the timer.
- * @param daemon if true, the thread is started as a daemon thread (the VM will exit when only daemon threads are running)
+ * @param daemon if `true`, the thread is started as a daemon thread (the VM will exit when only daemon threads are running).
  */
 public fun fixedRateTimer(name: String? = null, daemon: Boolean = false, startAt: Date, period: Long, action: TimerTask.() -> Unit): Timer {
     val timer = if (name == null) Timer(daemon) else Timer(name, daemon)
@@ -119,7 +119,7 @@ public fun fixedRateTimer(name: String? = null, daemon: Boolean = false, startAt
 }
 
 /**
- * Wraps the specified [action] in a `TimerTask`.
+ * Wraps the specified [action] in a [TimerTask].
  */
 public fun timerTask(action: TimerTask.() -> Unit): TimerTask = object : TimerTask() {
     public override fun run() {

libraries/stdlib/src/kotlin/io/Console.kt

@@ -5,17 +5,17 @@ import java.io.InputStreamReader
 import java.io.BufferedReader
 
 /**
- * Returns the default buffer size when working with buffered streams
+ * Returns the default buffer size when working with buffered streams.
  */
 public val defaultBufferSize: Int = 64 * 1024
 
 /**
- * Returns the default block size for forEachBlock()
+ * Returns the default block size for forEachBlock().
  */
 public val defaultBlockSize: Int = 4096
 
 /**
- * Returns the minimum block size for forEachBlock()
+ * Returns the minimum block size for forEachBlock().
  */
 public val minimumBlockSize: Int = 512
 
@@ -168,6 +168,6 @@ private val stdin: BufferedReader = BufferedReader(InputStreamReader(object : In
 /**
  * Reads a line of input from the standard input stream.
  *
- * @return the line read or null if the input stream is redirected to a file and the end of file has been reached.
+ * @return the line read or `null` if the input stream is redirected to a file and the end of file has been reached.
  */
 public fun readLine(): String? = stdin.readLine()

libraries/stdlib/src/kotlin/io/Exceptions.kt

@@ -15,7 +15,7 @@ private fun constructMessage(file: File, other: File?, reason: String?): String
 }
 
 /**
- * A base exception class for file system exceptions
+ * A base exception class for file system exceptions.
  */
 open public class FileSystemException(public val file: File,
                                       public val other: File? = null,
@@ -23,21 +23,21 @@ open public class FileSystemException(public val file: File,
 ) : IOException(constructMessage(file, other, reason))
 
 /**
- * An exception class which is used when some file to create or copy to already exists
+ * An exception class which is used when some file to create or copy to already exists.
  */
 public class FileAlreadyExistsException(file: File,
                                         other: File? = null,
                                         reason: String? = null) : FileSystemException(file, other, reason)
 
 /**
- * An exception class which is used when we have not enough access for some operation
+ * An exception class which is used when we have not enough access for some operation.
  */
 public class AccessDeniedException(file: File,
                                    other: File? = null,
                                    reason: String? = null) : FileSystemException(file, other, reason)
 
 /**
- * An exception class which is used when file to copy does not exist
+ * An exception class which is used when file to copy does not exist.
  */
 public class NoSuchFileException(file: File,
                                  other: File? = null,

libraries/stdlib/src/kotlin/io/ReadWrite.kt

@@ -14,7 +14,7 @@ public fun File.reader(): FileReader = FileReader(this)
 /**
  * Returns a new [BufferedReader] for reading the content of this file.
  *
- * @param bufferSize necessary size of the buffer
+ * @param bufferSize necessary size of the buffer.
  */
 public fun File.bufferedReader(bufferSize: Int = defaultBufferSize): BufferedReader = reader().buffered(bufferSize)
 
@@ -26,7 +26,7 @@ public fun File.writer(): FileWriter = FileWriter(this)
 /**
  * Returns a new [BufferedWriter] for writing the content of this file.
  *
- * @param bufferSize necessary size of the buffer
+ * @param bufferSize necessary size of the buffer.
  */
 public fun File.bufferedWriter(bufferSize: Int = defaultBufferSize): BufferedWriter = writer().buffered(bufferSize)
 
@@ -38,9 +38,9 @@ public fun File.printWriter(): PrintWriter = PrintWriter(bufferedWriter())
 /**
  * Gets the entire content of this file as a byte array.
  *
- * This method is not recommended on huge files. It has an internal limitation of 2 GB byte array size
+ * This method is not recommended on huge files. It has an internal limitation of 2 GB byte array size.
  *
- * @return the entire content of this file as a byte array
+ * @return the entire content of this file as a byte array.
  */
 public fun File.readBytes(): ByteArray = FileInputStream(this).use { it.readBytes(length().toInt()) }
 
@@ -48,34 +48,34 @@ public fun File.readBytes(): ByteArray = FileInputStream(this).use { it.readByte
  * Sets the content of this file as an [array] of bytes.
  * If this file already exists, it becomes overwritten.
  *
- * @param array byte array to write into this file
+ * @param array byte array to write into this file.
  */
 public fun File.writeBytes(array: ByteArray): Unit = FileOutputStream(this).use { it.write(array) }
 
 /**
  * Appends an [array] of bytes to the content of this file.
  *
- * @param array byte array to append to this file
+ * @param array byte array to append to this file.
  */
 public fun File.appendBytes(array: ByteArray): Unit = FileOutputStream(this, true).use { it.write(array) }
 
 /**
  * Gets the entire content of this file as a String using specified [charset].
  *
- * This method is not recommended on huge files. It has an internal limitation of 2 GB file size
+ * This method is not recommended on huge files. It has an internal limitation of 2 GB file size.
  *
- * @param charset character set to use
- * @return the entire content of this file as a String
+ * @param charset character set to use.
+ * @return the entire content of this file as a String.
  */
 public fun File.readText(charset: String): String = readBytes().toString(charset)
 
 /**
  * Gets the entire content of this file as a String using UTF-8 or specified [charset].
  *
- * This method is not recommended on huge files. It has an internal limitation of 2 GB file size
+ * This method is not recommended on huge files. It has an internal limitation of 2 GB file size.
  *
- * @param charset character set to use
- * @return the entire content of this file as a String
+ * @param charset character set to use.
+ * @return the entire content of this file as a String.
  */
 public fun File.readText(charset: Charset = Charsets.UTF_8): String = readBytes().toString(charset)
 
@@ -83,8 +83,8 @@ public fun File.readText(charset: Charset = Charsets.UTF_8): String = readBytes(
  * Sets the content of this file as [text] encoded using the specified [charset].
  * If this file exists, it becomes overwritten.
  *
- * @param text text to write into file
- * @param charset character set to use
+ * @param text text to write into file.
+ * @param charset character set to use.
  */
 public fun File.writeText(text: String, charset: String): Unit = writeBytes(text.toByteArray(charset))
 
@@ -92,24 +92,24 @@ public fun File.writeText(text: String, charset: String): Unit = writeBytes(text
  * Sets the content of this file as [text] encoded using UTF-8 or specified [charset].
  * If this file exists, it becomes overwritten.
  *
- * @param text text to write into file
- * @param charset character set to use
+ * @param text text to write into file.
+ * @param charset character set to use.
  */
 public fun File.writeText(text: String, charset: Charset = Charsets.UTF_8): Unit = writeBytes(text.toByteArray(charset))
 
 /**
  * Appends [text] to the content of this file using UTF-8 or the specified [charset].
  *
- * @param text text to append to file
- * @param charset character set to use
+ * @param text text to append to file.
+ * @param charset character set to use.
  */
 public fun File.appendText(text: String, charset: Charset = Charsets.UTF_8): Unit = appendBytes(text.toByteArray(charset))
 
 /**
  * Appends [text] to the content of the file using the specified [charset].
  *
- * @param text text to append to file
- * @param charset character set to use
+ * @param text text to append to file.
+ * @param charset character set to use.
  */
 public fun File.appendText(text: String, charset: String): Unit = appendBytes(text.toByteArray(charset))
 
@@ -120,7 +120,7 @@ public fun File.appendText(text: String, charset: String): Unit = appendBytes(te
  *
  * You can use this function for huge files.
  *
- * @param operation function to process file blocks
+ * @param operation function to process file blocks.
  */
 public fun File.forEachBlock(operation: (ByteArray, Int) -> Unit): Unit = forEachBlock(operation, defaultBlockSize)
 
@@ -130,8 +130,8 @@ public fun File.forEachBlock(operation: (ByteArray, Int) -> Unit): Unit = forEac
  *
  * You can use this function for huge files.
  *
- * @param operation function to process file blocks
- * @param blockSize size of a block, replaced by 512 if it's less, 4096 by default
+ * @param operation function to process file blocks.
+ * @param blockSize size of a block, replaced by 512 if it's less, 4096 by default.
  */
 public fun File.forEachBlock(operation: (ByteArray, Int) -> Unit, blockSize: Int): Unit {
     val arr = ByteArray(if (blockSize < minimumBlockSize) minimumBlockSize else blockSize)
@@ -157,8 +157,8 @@ public fun File.forEachBlock(operation: (ByteArray, Int) -> Unit, blockSize: Int
  *
  * You may use this function on huge files.
  *
- * @param charset character set to use
- * @param operation function to process file lines
+ * @param charset character set to use.
+ * @param operation function to process file lines.
  */
 public fun File.forEachLine(charset: Charset = Charsets.UTF_8, operation: (line: String) -> Unit): Unit {
     // Note: close is called at forEachLine
@@ -170,8 +170,8 @@ public fun File.forEachLine(charset: Charset = Charsets.UTF_8, operation: (line:
  *
  * You may use this function on huge files.
  *
- * @param charset character set to use
- * @param operation function to process file lines
+ * @param charset character set to use.
+ * @param operation function to process file lines.
  */
 public fun File.forEachLine(charset: String, operation: (line: String) -> Unit): Unit = forEachLine(Charset.forName(charset), operation)
 
@@ -180,8 +180,8 @@ public fun File.forEachLine(charset: String, operation: (line: String) -> Unit):
  *
  * Do not use this function for huge files.
  *
- * @param charset character set to use
- * @return list of file lines
+ * @param charset character set to use.
+ * @return list of file lines.
  */
 public fun File.readLines(charset: String): List<String> = readLines(Charset.forName(charset))
 
@@ -204,8 +204,8 @@ public fun File.outputStream(): OutputStream {
  *
  * Do not use this function for huge files.
  *
- * @param charset character set to use
- * @return list of file lines
+ * @param charset character set to use.
+ * @return list of file lines.
  */
 public fun File.readLines(charset: Charset = Charsets.UTF_8): List<String> {
     val result = ArrayList<String>()
@@ -223,9 +223,9 @@ public fun Writer.buffered(bufferSize: Int = defaultBufferSize): BufferedWriter
 
 /**
  * Iterates through each line of this reader, calls [block] for each line read
- * and closes the [Reader] when it's completed
+ * and closes the [Reader] when it's completed.
  *
- * @param block function to process file lines
+ * @param block function to process file lines.
  */
 public fun Reader.forEachLine(block: (String) -> Unit): Unit = useLines { it.forEach(block) }
 
@@ -238,7 +238,7 @@ public inline fun <T> Reader.useLines(block: (Sequence<String>) -> T): T =
         buffered().use { block(it.lines()) }
 
 /**
- * Returns a sequence of corresponding file lines
+ * Returns a sequence of corresponding file lines.
  *
  * *Note*: the caller must close the underlying `BufferedReader`
  * when the iteration is finished; as the user may not complete the iteration loop (e.g. using a method like find() or any() on the iterator
@@ -280,11 +280,11 @@ private class LinesSequence(private val reader: BufferedReader) : Sequence<Strin
 }
 
 /**
- * Reads this reader completely as a String
+ * Reads this reader completely as a String.
  *
  * *Note*:  It is the caller's responsibility to close this reader.
  *
- * @return the string with corresponding file content
+ * @return the string with corresponding file content.
  */
 public fun Reader.readText(): String {
     val buffer = StringWriter()
@@ -295,11 +295,11 @@ public fun Reader.readText(): String {
 /**
  * Copies this reader to the given [out] writer, returning the number of bytes copied.
  *
- * **Note** it is the caller's responsibility to close both of these resources
+ * **Note** it is the caller's responsibility to close both of these resources.
  *
- * @param out writer to write to
- * @param bufferSize size of character buffer to use in process
- * @return number of bytes copies
+ * @param out writer to write to.
+ * @param bufferSize size of character buffer to use in process.
+ * @return number of bytes copies.
  */
 public fun Reader.copyTo(out: Writer, bufferSize: Int = defaultBufferSize): Long {
     var charsCopied: Long = 0
@@ -318,8 +318,8 @@ public fun Reader.copyTo(out: Writer, bufferSize: Int = defaultBufferSize): Long
  *
  * This method is not recommended on huge files.
  *
- * @param charset a character set to use
- * @return a string with this URL entire content
+ * @param charset a character set to use.
+ * @return a string with this URL entire content.
  */
 public fun URL.readText(charset: String): String = readBytes().toString(charset)
 
@@ -328,26 +328,26 @@ public fun URL.readText(charset: String): String = readBytes().toString(charset)
  *
  * This method is not recommended on huge files.
  *
- * @param charset a character set to use
- * @return a string with this URL entire content
+ * @param charset a character set to use.
+ * @return a string with this URL entire content.
  */
 public fun URL.readText(charset: Charset = Charsets.UTF_8): String = readBytes().toString(charset)
 
 /**
- * Reads the entire content of the URL as byte array
+ * Reads the entire content of the URL as byte array.
  *
  * This method is not recommended on huge files.
  *
- * @return a byte array with this URL entire content
+ * @return a byte array with this URL entire content.
  */
 public fun URL.readBytes(): ByteArray = openStream().use { it.readBytes() }
 
 /**
  * Executes the given [block] function on this resource and then closes it down correctly whether an exception
- * is thrown or not
+ * is thrown or not.
  *
- * @param block a function to process this closable resource
- * @return the result of [block] function on this closable resource
+ * @param block a function to process this closable resource.
+ * @return the result of [block] function on this closable resource.
  */
 public inline fun <T : Closeable, R> T.use(block: (T) -> R): R {
     var closed = false

libraries/stdlib/src/kotlin/io/files/FilePathComponents.kt

@@ -16,7 +16,7 @@ import kotlin.text.Regex
  * which is incorrect for current OS. For instance, in Unix function cannot detect
  * network root names like //network.name/root, but can detect Windows roots like C:/.
  *
- * @return string representing the root for this file, or empty string is this file name is relative
+ * @return string representing the root for this file, or empty string is this file name is relative.
  */
 private fun String.getRootName(): String {
     // Note: separators should be already replaced to system ones
@@ -61,7 +61,7 @@ private fun String.getRootName(): String {
  * which is incorrect for current OS. For instance, in Unix function cannot detect
  * network root names like //network.name/root, but can detect Windows roots like C:/.
  *
- * @return string representing the root for this file, or empty string is this file name is relative
+ * @return string representing the root for this file, or empty string is this file name is relative.
  */
 public val File.rootName: String
     get() = separatorsToSystem().getRootName()
@@ -69,7 +69,7 @@ public val File.rootName: String
 /**
  * Returns root component of this abstract name, like / from /home/user, or C:\ from C:\file.tmp,
  * or //my.host/home for //my.host/home/user,
- * or null if this name is relative, like bar/gav
+ * or `null` if this name is relative, like bar/gav
  */
 public val File.root: File?
     get() {
@@ -105,9 +105,9 @@ public fun File.filePathComponents(): FilePathComponents {
  * beginning from component [beginIndex], inclusive,
  * ending at component [endIndex], exclusive.
  * Number 0 belongs to a component closest to the root,
- * number count-1 belongs to a component farthest from the root
+ * number count-1 belongs to a component farthest from the root.
  * @throws IllegalArgumentException if [beginIndex] is negative,
 * or [endIndex] is greater than existing number of components,
-* or [beginIndex] is greater than [endIndex]
+* or [beginIndex] is greater than [endIndex].
  */
 public fun File.subPath(beginIndex: Int, endIndex: Int): File = filePathComponents().subPath(beginIndex, endIndex)

libraries/stdlib/src/kotlin/io/files/FileTreeWalk.kt

@@ -26,12 +26,12 @@ public enum class FileWalkDirection {
  * If [start] is just a file, walker iterates only it.
  * If [start] does not exist, walker does not do any iterations at all.
  *
- * @param start directory to walk into
+ * @param start directory to walk into.
  * @param direction selects top-down or bottom-up order (in other words, parents first or children first).
- * @param enter is called on any entered directory before its files are visited and before it is visited itself
- * @param leave is called on any left directory after its files are visited and after it is visited itself
- * @param fail is called on a directory when it's impossible to get its file list
- * @param filter is called just before visiting a file, and if false is returned, file is not visited
+ * @param enter is called on any entered directory before its files are visited and before it is visited itself.
+ * @param leave is called on any left directory after its files are visited and after it is visited itself.
+ * @param fail is called on a directory when it's impossible to get its file list.
+ * @param filter is called just before visiting a file, and if `false` is returned, file is not visited.
  * @param maxDepth is maximum walking depth, it must be positive. With a value of 1,
  * walker visits [start] and all its children, with a value of 2 also grandchildren, etc.
  */
@@ -188,7 +188,7 @@ public class FileTreeWalk(private val start: File,
 
     /**
      * Sets enter directory [function].
-     * Enter [function] is called BEFORE the corresponding directory and its files are visited
+     * Enter [function] is called BEFORE the corresponding directory and its files are visited.
      */
     public fun enter(function: (File) -> Unit): FileTreeWalk {
         return FileTreeWalk(start, direction, function, leave, fail, filter, maxDepth)
@@ -196,7 +196,7 @@ public class FileTreeWalk(private val start: File,
 
     /**
      * Sets leave directory [function].
-     * Leave [function] is called AFTER the corresponding directory and its files are visited
+     * Leave [function] is called AFTER the corresponding directory and its files are visited.
      */
     public fun leave(function: (File) -> Unit): FileTreeWalk {
         return FileTreeWalk(start, direction, enter, function, fail, filter, maxDepth)
@@ -214,8 +214,8 @@ public class FileTreeWalk(private val start: File,
     /**
      * Sets filter [predicate].
      * Filter [predicate] function is called before visiting files and entering directories.
-     * If it returns false, file is not visited, directory is not entered and all its content is also not visited.
-     * If it returns true, everything goes in the regular way
+     * If it returns `false`, file is not visited, directory is not entered and all its content is also not visited.
+     * If it returns `true`, everything goes in the regular way.
      */
     public fun filter(predicate: (File) -> Boolean): FileTreeWalk {
         return FileTreeWalk(start, direction, enter, leave, fail, predicate, maxDepth)
@@ -223,7 +223,7 @@ public class FileTreeWalk(private val start: File,
 
     /**
      * Sets maximum [depth] of walk. Int.MAX_VALUE is used for unlimited.
-     * Negative and zero values are not allowed
+     * Negative and zero values are not allowed.
      */
     public fun maxDepth(depth: Int): FileTreeWalk {
         if (depth <= 0)
@@ -252,7 +252,7 @@ public class FileTreeWalk(private val start: File,
         }
     }
 
-    /** Returns an associated file iterator */
+    /** Returns an associated file iterator. */
     override public fun iterator(): Iterator<File> {
         return it
     }
@@ -261,20 +261,20 @@ public class FileTreeWalk(private val start: File,
 /**
  * Gets a sequence for visiting this directory and all its content.
  *
- * @param direction walk direction, top-down (by default) or bottom-up
+ * @param direction walk direction, top-down (by default) or bottom-up.
  */
 public fun File.walk(direction: FileWalkDirection = FileWalkDirection.TOP_DOWN): FileTreeWalk =
         FileTreeWalk(this, direction)
 
 /**
  * Gets a sequence for visiting this directory and all its content in top-down order.
- * Depth-first search is used and directories are visited before all their files
+ * Depth-first search is used and directories are visited before all their files.
  */
 public fun File.walkTopDown(): FileTreeWalk = walk(FileWalkDirection.TOP_DOWN)
 
 /**
  * Gets a sequence for visiting this directory and all its content in bottom-up order.
- * Depth-first search is used and directories are visited after all their files
+ * Depth-first search is used and directories are visited after all their files.
  */
 public fun File.walkBottomUp(): FileTreeWalk = walk(FileWalkDirection.BOTTOM_UP)
 
@@ -282,7 +282,7 @@ public fun File.walkBottomUp(): FileTreeWalk = walk(FileWalkDirection.BOTTOM_UP)
  * Recursively process this file and all children with the given block.
  * Note that if this file doesn't exist, then the block will be executed on it anyway.
  *
- * @param function the function to call on each file
+ * @param function the function to call on each file.
  */
 deprecated("It's recommended to use walkTopDown() / walkBottomUp()")
 public fun File.recurse(function: (File) -> Unit): Unit {

libraries/stdlib/src/kotlin/io/files/Utils.kt

@@ -13,8 +13,8 @@ import java.util.ArrayList
  *
  * @return a file object corresponding to a newly-created directory.
 *
- * @throws IOException in case of input/output error
- * @throws IllegalArgumentException if [prefix] is shorter than three symbols
+ * @throws IOException in case of input/output error.
+ * @throws IllegalArgumentException if [prefix] is shorter than three symbols.
  */
 public fun createTempDir(prefix: String = "tmp", suffix: String? = null, directory: File? = null): File {
     val dir = File.createTempFile(prefix, suffix, directory)
@@ -35,21 +35,21 @@ public fun createTempDir(prefix: String = "tmp", suffix: String? = null, directo
  *
  * @return a file object corresponding to a newly-created file.
 *
- * @throws IOException in case of input/output error
- * @throws IllegalArgumentException if [prefix] is shorter than three symbols
+ * @throws IOException in case of input/output error.
+ * @throws IllegalArgumentException if [prefix] is shorter than three symbols.
  */
 public fun createTempFile(prefix: String = "tmp", suffix: String? = null, directory: File? = null): File {
     return File.createTempFile(prefix, suffix, directory)
 }
 
 /**
- * Returns this if this file is a directory, or the parent if it is a file inside a directory
+ * Returns this if this file is a directory, or the parent if it is a file inside a directory.
  */
 public val File.directory: File
     get() = if (isDirectory()) this else parent!!
 
 /**
- * Returns parent of this abstract path name, or null if it has no parent
+ * Returns parent of this abstract path name, or `null` if it has no parent.
  */
 public val File.parent: File?
     get() = getParentFile()
@@ -61,13 +61,13 @@ public val File.canonicalPath: String
     get() = getCanonicalPath()
 
 /**
- * Returns the file name
+ * Returns the file name.
  */
 public val File.name: String
     get() = getName()
 
 /**
- * Returns the file path
+ * Returns the file path.
  */
 public val File.path: String
     get() = getPath()
@@ -81,7 +81,7 @@ public val File.extension: String
 /**
  * Replaces all separators in the string used to separate directories with system ones and returns the resulting string.
  *
- * @return the pathname with system separators
+ * @return the pathname with system separators.
  */
 public fun String.separatorsToSystem(): String {
     val otherSep = if (File.separator == "/") "\\" else "/"
@@ -91,7 +91,7 @@ public fun String.separatorsToSystem(): String {
 /**
  * Replaces all path separators in the string with system ones and returns the resulting string.
  *
- * @return the pathname with system separators
+ * @return the pathname with system separators.
  */
 public fun String.pathSeparatorsToSystem(): String {
     val otherSep = if (File.pathSeparator == ":") ";" else ":"
@@ -101,22 +101,22 @@ public fun String.pathSeparatorsToSystem(): String {
 /**
  * Replaces path and directories separators with corresponding system ones and returns the resulting string.
  *
- * @return the pathname with system separators
+ * @return the pathname with system separators.
  */
 public fun String.allSeparatorsToSystem(): String {
     return separatorsToSystem().pathSeparatorsToSystem()
 }
 
-/** Creates a new reader for the string */
+/** Creates a new reader for the string. */
 public fun String.reader(): StringReader = StringReader(this)
 
-/** Creates a new byte input stream for the string */
+/** Creates a new byte input stream for the string. */
 public fun String.byteInputStream(charset: Charset = Charsets.UTF_8): InputStream = ByteArrayInputStream(toByteArray(charset))
 
 /**
- * Returns a pathname of this file with all path separators replaced with File.pathSeparator
+ * Returns a pathname of this file with all path separators replaced with File.pathSeparator.
  *
- * @return the pathname with system separators
+ * @return the pathname with system separators.
  */
 public fun File.separatorsToSystem(): String {
     return toString().separatorsToSystem()
@@ -133,7 +133,7 @@ public val File.nameWithoutExtension: String
  * Note that the [base] file is treated as a directory.
  * If this file matches the [base] file, then an empty string will be returned.
  *
- * @return relative path from [base] to this
+ * @return relative path from [base] to this.
 *
  * @throws IllegalArgumentException if child and parent have different roots.
  */
@@ -189,18 +189,18 @@ public fun File.relativePath(descendant: File): String {
  * Copies this file to the given output [dst], returning the number of bytes copied.
  *
  * If some directories on a way to the [dst] are missing, then they will be created.
- * If the [dst] file already exists, then this function will fail unless [overwrite] argument is set to true.
+ * If the [dst] file already exists, then this function will fail unless [overwrite] argument is set to `true`.
  * Otherwise this file overwrites [dst] if it's a file to, or is written into [dst] if it's a directory.
  *
  * Note: this function fails if you call it on a directory.
  * If you want to copy directories, use 'copyRecursively' function instead.
  *
- * @param overwrite true if destination overwrite is allowed
+ * @param overwrite `true` if destination overwrite is allowed.
  * @param bufferSize the buffer size to use when copying.
  * @return the number of bytes copied
- * @throws NoSuchFileException if the source file doesn't exist
- * @throws FileAlreadyExistsException if the destination file already exists and 'rewrite' argument is set to false
- * @throws IOException if any errors occur while copying
+ * @throws NoSuchFileException if the source file doesn't exist.
+ * @throws FileAlreadyExistsException if the destination file already exists and 'rewrite' argument is set to `false`.
+ * @throws IOException if any errors occur while copying.
  */
 public fun File.copyTo(dst: File, overwrite: Boolean = false, bufferSize: Int = defaultBufferSize): Long {
     if (!exists()) {
@@ -241,7 +241,7 @@ public enum class OnErrorAction {
     TERMINATE
 }
 
-/** Private exception class, used to terminate recursive copying */
+/** Private exception class, used to terminate recursive copying. */
 private class TerminateException(file: File) : FileSystemException(file) {}
 
 /**
@@ -258,7 +258,7 @@ private class TerminateException(file: File) : FileSystemException(file) {}
  * AccessDeniedException - if there was an attempt to open a directory that didn't succeed.
  * IOException - if some problems occur when copying.
  *
- * @return false if the copying was terminated, true otherwise.
+ * @return `false` if the copying was terminated, `true` otherwise.
 *
 * Note that if this function fails, then partial copying may have taken place.
  */
@@ -305,13 +305,13 @@ public fun File.copyRecursively(dst: File,
  * Delete this file with all its children.
  * Note that if this operation fails then partial deletion may have taken place.
  *
- * @return true if the file or directory is successfully deleted, false otherwise.
+ * @return `true` if the file or directory is successfully deleted, `false` otherwise.
  */
 public fun File.deleteRecursively(): Boolean = walkBottomUp().fold(exists(), { res, it -> it.delete() && res })
 
 /**
  * Returns an array of files and directories in the directory that match the specified [filter]
- * or null if this file does not denote a directory.
+ * or `null` if this file does not denote a directory.
  */
 public fun File.listFiles(filter: (file: File) -> Boolean): Array<File>? = listFiles(FileFilter(filter))
 
@@ -321,7 +321,7 @@ public fun File.listFiles(filter: (file: File) -> Boolean): Array<File>? = listF
  * So if [other] has N components, first N components of `this` must be the same as in [other].
  * For relative [other], `this` can belong to any root.
  *
- * @return true if this path starts with [other] path, false otherwise
+ * @return `true` if this path starts with [other] path, `false` otherwise.
  */
 public fun File.startsWith(other: File): Boolean {
     val components = filePathComponents()
@@ -338,7 +338,7 @@ public fun File.startsWith(other: File): Boolean {
  * So if [other] has N components, first N components of `this` must be the same as in [other].
  * For relative [other], `this` can belong to any root.
  *
- * @return true if this path starts with [other] path, false otherwise
+ * @return `true` if this path starts with [other] path, `false` otherwise.
  */
 public fun File.startsWith(other: String): Boolean = startsWith(File(other))
 
@@ -348,7 +348,7 @@ public fun File.startsWith(other: String): Boolean = startsWith(File(other))
  * So if [other] has N components, last N components of `this` must be the same as in [other].
  * For relative [other], `this` can belong to any root.
  *
- * @return true if this path ends with [other] path, false otherwise
+ * @return `true` if this path ends with [other] path, `false` otherwise.
  */
 public fun File.endsWith(other: File): Boolean {
     val components = filePathComponents()
@@ -366,15 +366,15 @@ public fun File.endsWith(other: File): Boolean {
  * So if [other] has N components, last N components of `this` must be the same as in [other].
  * For relative [other], `this` can belong to any root.
  *
- * @return true if this path ends with [other] path, false otherwise
+ * @return `true` if this path ends with [other] path, `false` otherwise.
  */
 public fun File.endsWith(other: String): Boolean = endsWith(File(other))
 
 /**
  * Removes all . and resolves all possible .. in this file name.
- * For instance, File("/foo/./bar/gav/../baaz").normalize is File("/foo/bar/baaz")
+ * For instance, `File("/foo/./bar/gav/../baaz").normalize()` is `File("/foo/bar/baaz")`.
  *
- * @return normalized pathname with . and possibly .. removed
+ * @return normalized pathname with . and possibly .. removed.
  */
 public fun File.normalize(): File {
     val components = filePathComponents()
@@ -395,11 +395,11 @@ public fun File.normalize(): File {
 /**
  * Adds [relative] file to this, considering this as a directory.
  * If [relative] has a root, [relative] is returned back.
- * For instance, File("/foo/bar").resolve(File("gav")) is File("/foo/bar/gav").
- * This function is complementary with (File.relativeTo),
- * so f.resolve(g.relativeTo(f)) == g should be always true except for different roots case.
+ * For instance, `File("/foo/bar").resolve(File("gav"))` is `File("/foo/bar/gav")`.
+ * This function is complementary with [relativeTo],
+ * so `f.resolve(g.relativeTo(f)) == g` should be always `true` except for different roots case.
  *
- * @return concatenated this and [relative] paths, or just [relative] if it's absolute
+ * @return concatenated this and [relative] paths, or just [relative] if it's absolute.
  */
 public fun File.resolve(relative: File): File {
     if (relative.root != null)
@@ -411,18 +411,18 @@ public fun File.resolve(relative: File): File {
 /**
  * Adds [relative] name to this, considering this as a directory.
  * If [relative] has a root, [relative] is returned back.
- * For instance, File("/foo/bar").resolve("gav") is File("/foo/bar/gav")
+ * For instance, `File("/foo/bar").resolve("gav")` is `File("/foo/bar/gav")`.
  *
- * @return concatenated this and [relative] paths, or just [relative] if it's absolute
+ * @return concatenated this and [relative] paths, or just [relative] if it's absolute.
  */
 public fun File.resolve(relative: String): File = resolve(File(relative))
 
 /**
  * Adds [relative] file to this parent directory.
  * If [relative] has a root or this has no parent directory, [relative] is returned back.
- * For instance, File("/foo/bar").resolveSibling(File("gav")) is File("/foo/gav")
+ * For instance, `File("/foo/bar").resolveSibling(File("gav"))` is `File("/foo/gav")`.
  *
- * @return concatenated this.parent and [relative] paths, or just [relative] if it's absolute or this has no parent
+ * @return concatenated this.parent and [relative] paths, or just [relative] if it's absolute or this has no parent.
  */
 public fun File.resolveSibling(relative: File): File {
     val components = filePathComponents()
@@ -432,9 +432,9 @@ public fun File.resolveSibling(relative: File): File {
 
 /**
  * Adds [relative] name to this parent directory.
- * If [relative] has a root or this has no parent directory, [relative] is returned back
- * For instance, File("/foo/bar").resolveSibling("gav") is File("/foo/gav")
+ * If [relative] has a root or this has no parent directory, [relative] is returned back.
+ * For instance, `File("/foo/bar").resolveSibling("gav")` is `File("/foo/gav")`.
  *
- * @return concatenated this.parent and [relative] paths, or just [relative] if it's absolute or this has no parent
+ * @return concatenated this.parent and [relative] paths, or just [relative] if it's absolute or this has no parent.
  */
 public fun File.resolveSibling(relative: String): File = resolveSibling(File(relative))