diff --git a/libraries/stdlib/src/kotlin/collections/ArraysJVM.kt b/libraries/stdlib/src/kotlin/collections/ArraysJVM.kt index f32a06ecc38..31541e22b02 100644 --- a/libraries/stdlib/src/kotlin/collections/ArraysJVM.kt +++ b/libraries/stdlib/src/kotlin/collections/ArraysJVM.kt @@ -87,6 +87,6 @@ public inline fun Collection.toTypedArray(): Array { return thisCollection.toArray(arrayOfNulls(thisCollection.size())) as Array } -/** 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 Array?.orEmpty(): Array = this ?: arrayOf() diff --git a/libraries/stdlib/src/kotlin/collections/JUtil.kt b/libraries/stdlib/src/kotlin/collections/JUtil.kt index 4577b4ee004..0b3971f7428 100644 --- a/libraries/stdlib/src/kotlin/collections/JUtil.kt +++ b/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 List.lastIndex: Int get() = this.size() - 1 -/** Returns true if the collection is not empty */ +/** Returns `true` if the collection is not empty. */ public fun Collection.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 Collection?.orEmpty(): Collection = 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 List?.orEmpty(): List = 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 Set?.orEmpty(): Set = this ?: emptySet() /** diff --git a/libraries/stdlib/src/kotlin/collections/Maps.kt b/libraries/stdlib/src/kotlin/collections/Maps.kt index e01cfac4717..b8024001b31 100644 --- a/libraries/stdlib/src/kotlin/collections/Maps.kt +++ b/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 Map.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 Map?.orEmpty() : Map = this ?: emptyMap() @@ -347,7 +347,7 @@ public fun Iterable>.toMap(): Map { public fun Map.toLinkedMap(): MutableMap = 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 Map.plus(pair: Pair): Map { val newMap = this.toLinkedMap() @@ -356,7 +356,7 @@ public fun Map.plus(pair: Pair): Map { } /** - * 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 Map.plus(pairs: Iterable>): Map { val newMap = this.toLinkedMap() @@ -365,7 +365,7 @@ public fun Map.plus(pairs: Iterable>): Map { } /** - * 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 Map.plus(map: Map): Map { val newMap = this.toLinkedMap() @@ -374,14 +374,14 @@ public fun Map.plus(map: Map): Map { } /** - * 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 Map.minus(key: K): Map { 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 Map.minus(keys: Iterable): Map { val result = LinkedHashMap() diff --git a/libraries/stdlib/src/kotlin/collections/MapsJVM.kt b/libraries/stdlib/src/kotlin/collections/MapsJVM.kt index 5fe02ce10ed..95c2567e48d 100644 --- a/libraries/stdlib/src/kotlin/collections/MapsJVM.kt +++ b/libraries/stdlib/src/kotlin/collections/MapsJVM.kt @@ -13,7 +13,7 @@ import java.util.Properties public fun MutableMap.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 , V> Map.toSortedMap(): SortedMap = 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 sortedMapOf(vararg values: Pair): SortedMap { /** - * Converts this [Map] to a [Properties] object + * Converts this [Map] to a [Properties] object. * * @sample test.collections.MapJVMTest.toProperties */ diff --git a/libraries/stdlib/src/kotlin/concurrent/Locks.kt b/libraries/stdlib/src/kotlin/concurrent/Locks.kt index de165615612..d6f3e2c42cb 100644 --- a/libraries/stdlib/src/kotlin/concurrent/Locks.kt +++ b/libraries/stdlib/src/kotlin/concurrent/Locks.kt @@ -33,8 +33,8 @@ public inline fun 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 ReentrantReadWriteLock.write(action: () -> T): T { diff --git a/libraries/stdlib/src/kotlin/concurrent/Thread.kt b/libraries/stdlib/src/kotlin/concurrent/Thread.kt index 238d9a9291c..e8c2df8b058 100644 --- a/libraries/stdlib/src/kotlin/concurrent/Thread.kt +++ b/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 diff --git a/libraries/stdlib/src/kotlin/concurrent/Timer.kt b/libraries/stdlib/src/kotlin/concurrent/Timer.kt index a2a71ec5d89..c3914266387 100644 --- a/libraries/stdlib/src/kotlin/concurrent/Timer.kt +++ b/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() { diff --git a/libraries/stdlib/src/kotlin/io/Console.kt b/libraries/stdlib/src/kotlin/io/Console.kt index 261d8ca271a..02023afc375 100644 --- a/libraries/stdlib/src/kotlin/io/Console.kt +++ b/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() diff --git a/libraries/stdlib/src/kotlin/io/Exceptions.kt b/libraries/stdlib/src/kotlin/io/Exceptions.kt index ebb089a273f..ed6acd54da3 100644 --- a/libraries/stdlib/src/kotlin/io/Exceptions.kt +++ b/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, diff --git a/libraries/stdlib/src/kotlin/io/ReadWrite.kt b/libraries/stdlib/src/kotlin/io/ReadWrite.kt index 3cb40161d7c..b2ea6d2c9bb 100644 --- a/libraries/stdlib/src/kotlin/io/ReadWrite.kt +++ b/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 = 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 { val result = ArrayList() @@ -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 Reader.useLines(block: (Sequence) -> 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 T.use(block: (T) -> R): R { var closed = false diff --git a/libraries/stdlib/src/kotlin/io/files/FilePathComponents.kt b/libraries/stdlib/src/kotlin/io/files/FilePathComponents.kt index 26004713e35..28df4e818a5 100644 --- a/libraries/stdlib/src/kotlin/io/files/FilePathComponents.kt +++ b/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) diff --git a/libraries/stdlib/src/kotlin/io/files/FileTreeWalk.kt b/libraries/stdlib/src/kotlin/io/files/FileTreeWalk.kt index 9e18784947b..cd5208efa86 100644 --- a/libraries/stdlib/src/kotlin/io/files/FileTreeWalk.kt +++ b/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 { 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 { diff --git a/libraries/stdlib/src/kotlin/io/files/Utils.kt b/libraries/stdlib/src/kotlin/io/files/Utils.kt index 8fb9be4e304..c3f4287249d 100644 --- a/libraries/stdlib/src/kotlin/io/files/Utils.kt +++ b/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? = listFiles(FileFilter(filter)) @@ -321,7 +321,7 @@ public fun File.listFiles(filter: (file: File) -> Boolean): Array? = 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))