correct some errors and omissions in stdlib doc comments

libraries/stdlib/src/Module.md

@@ -60,6 +60,10 @@ Java reflection.
 
 Functions for writing tests.
 
+# Package kotlin.text
+
+Functions for working with text and regular expressions.
+
 # Package kotlin.util
 
 Utility functions.

libraries/stdlib/src/generated/_Generators.kt

@@ -392,8 +392,8 @@ public fun <T, R, V> Stream<T>.merge(stream: Stream<R>, transform: (T, R) -> V):
 
 /**
  * Splits original collection into pair of collections,
- * where *first* collection contains elements for which [predicate] yielded [true],
- * while *second* collection contains elements for which [predicate] yielded [false].
+ * where *first* collection contains elements for which [predicate] yielded `true`,
+ * while *second* collection contains elements for which [predicate] yielded `false`.
  */
 public inline fun <T> Array<out T>.partition(predicate: (T) -> Boolean): Pair<List<T>, List<T>> {
     val first = ArrayList<T>()
@@ -410,8 +410,8 @@ public inline fun <T> Array<out T>.partition(predicate: (T) -> Boolean): Pair<Li
 
 /**
  * Splits original collection into pair of collections,
- * where *first* collection contains elements for which [predicate] yielded [true],
- * while *second* collection contains elements for which [predicate] yielded [false].
+ * where *first* collection contains elements for which [predicate] yielded `true`,
+ * while *second* collection contains elements for which [predicate] yielded `false`.
  */
 public inline fun BooleanArray.partition(predicate: (Boolean) -> Boolean): Pair<List<Boolean>, List<Boolean>> {
     val first = ArrayList<Boolean>()
@@ -428,8 +428,8 @@ public inline fun BooleanArray.partition(predicate: (Boolean) -> Boolean): Pair<
 
 /**
  * Splits original collection into pair of collections,
- * where *first* collection contains elements for which [predicate] yielded [true],
- * while *second* collection contains elements for which [predicate] yielded [false].
+ * where *first* collection contains elements for which [predicate] yielded `true`,
+ * while *second* collection contains elements for which [predicate] yielded `false`.
  */
 public inline fun ByteArray.partition(predicate: (Byte) -> Boolean): Pair<List<Byte>, List<Byte>> {
     val first = ArrayList<Byte>()
@@ -446,8 +446,8 @@ public inline fun ByteArray.partition(predicate: (Byte) -> Boolean): Pair<List<B
 
 /**
  * Splits original collection into pair of collections,
- * where *first* collection contains elements for which [predicate] yielded [true],
- * while *second* collection contains elements for which [predicate] yielded [false].
+ * where *first* collection contains elements for which [predicate] yielded `true`,
+ * while *second* collection contains elements for which [predicate] yielded `false`.
  */
 public inline fun CharArray.partition(predicate: (Char) -> Boolean): Pair<List<Char>, List<Char>> {
     val first = ArrayList<Char>()
@@ -464,8 +464,8 @@ public inline fun CharArray.partition(predicate: (Char) -> Boolean): Pair<List<C
 
 /**
  * Splits original collection into pair of collections,
- * where *first* collection contains elements for which [predicate] yielded [true],
- * while *second* collection contains elements for which [predicate] yielded [false].
+ * where *first* collection contains elements for which [predicate] yielded `true`,
+ * while *second* collection contains elements for which [predicate] yielded `false`.
  */
 public inline fun DoubleArray.partition(predicate: (Double) -> Boolean): Pair<List<Double>, List<Double>> {
     val first = ArrayList<Double>()
@@ -482,8 +482,8 @@ public inline fun DoubleArray.partition(predicate: (Double) -> Boolean): Pair<Li
 
 /**
  * Splits original collection into pair of collections,
- * where *first* collection contains elements for which [predicate] yielded [true],
- * while *second* collection contains elements for which [predicate] yielded [false].
+ * where *first* collection contains elements for which [predicate] yielded `true`,
+ * while *second* collection contains elements for which [predicate] yielded `false`.
  */
 public inline fun FloatArray.partition(predicate: (Float) -> Boolean): Pair<List<Float>, List<Float>> {
     val first = ArrayList<Float>()
@@ -500,8 +500,8 @@ public inline fun FloatArray.partition(predicate: (Float) -> Boolean): Pair<List
 
 /**
  * Splits original collection into pair of collections,
- * where *first* collection contains elements for which [predicate] yielded [true],
- * while *second* collection contains elements for which [predicate] yielded [false].
+ * where *first* collection contains elements for which [predicate] yielded `true`,
+ * while *second* collection contains elements for which [predicate] yielded `false`.
  */
 public inline fun IntArray.partition(predicate: (Int) -> Boolean): Pair<List<Int>, List<Int>> {
     val first = ArrayList<Int>()
@@ -518,8 +518,8 @@ public inline fun IntArray.partition(predicate: (Int) -> Boolean): Pair<List<Int
 
 /**
  * Splits original collection into pair of collections,
- * where *first* collection contains elements for which [predicate] yielded [true],
- * while *second* collection contains elements for which [predicate] yielded [false].
+ * where *first* collection contains elements for which [predicate] yielded `true`,
+ * while *second* collection contains elements for which [predicate] yielded `false`.
  */
 public inline fun LongArray.partition(predicate: (Long) -> Boolean): Pair<List<Long>, List<Long>> {
     val first = ArrayList<Long>()
@@ -536,8 +536,8 @@ public inline fun LongArray.partition(predicate: (Long) -> Boolean): Pair<List<L
 
 /**
  * Splits original collection into pair of collections,
- * where *first* collection contains elements for which [predicate] yielded [true],
- * while *second* collection contains elements for which [predicate] yielded [false].
+ * where *first* collection contains elements for which [predicate] yielded `true`,
+ * while *second* collection contains elements for which [predicate] yielded `false`.
  */
 public inline fun ShortArray.partition(predicate: (Short) -> Boolean): Pair<List<Short>, List<Short>> {
     val first = ArrayList<Short>()
@@ -554,8 +554,8 @@ public inline fun ShortArray.partition(predicate: (Short) -> Boolean): Pair<List
 
 /**
  * Splits original collection into pair of collections,
- * where *first* collection contains elements for which [predicate] yielded [true],
- * while *second* collection contains elements for which [predicate] yielded [false].
+ * where *first* collection contains elements for which [predicate] yielded `true`,
+ * while *second* collection contains elements for which [predicate] yielded `false`.
  */
 public inline fun <T> Iterable<T>.partition(predicate: (T) -> Boolean): Pair<List<T>, List<T>> {
     val first = ArrayList<T>()
@@ -572,8 +572,8 @@ public inline fun <T> Iterable<T>.partition(predicate: (T) -> Boolean): Pair<Lis
 
 /**
  * Splits original collection into pair of collections,
- * where *first* collection contains elements for which [predicate] yielded [true],
- * while *second* collection contains elements for which [predicate] yielded [false].
+ * where *first* collection contains elements for which [predicate] yielded `true`,
+ * while *second* collection contains elements for which [predicate] yielded `false`.
  */
 public inline fun <T> Sequence<T>.partition(predicate: (T) -> Boolean): Pair<List<T>, List<T>> {
     val first = ArrayList<T>()
@@ -592,8 +592,8 @@ public inline fun <T> Sequence<T>.partition(predicate: (T) -> Boolean): Pair<Lis
 deprecated("Migrate to using Sequence<T> and respective functions")
 /**
  * Splits original collection into pair of collections,
- * where *first* collection contains elements for which [predicate] yielded [true],
- * while *second* collection contains elements for which [predicate] yielded [false].
+ * where *first* collection contains elements for which [predicate] yielded `true`,
+ * while *second* collection contains elements for which [predicate] yielded `false`.
  */
 public inline fun <T> Stream<T>.partition(predicate: (T) -> Boolean): Pair<List<T>, List<T>> {
     val first = ArrayList<T>()
@@ -610,8 +610,8 @@ public inline fun <T> Stream<T>.partition(predicate: (T) -> Boolean): Pair<List<
 
 /**
  * Splits original collection into pair of collections,
- * where *first* collection contains elements for which [predicate] yielded [true],
- * while *second* collection contains elements for which [predicate] yielded [false].
+ * where *first* collection contains elements for which [predicate] yielded `true`,
+ * while *second* collection contains elements for which [predicate] yielded `false`.
  */
 public inline fun String.partition(predicate: (Char) -> Boolean): Pair<String, String> {
     val first = StringBuilder()
@@ -627,7 +627,7 @@ public inline fun String.partition(predicate: (Char) -> Boolean): Pair<String, S
 }
 
 /**
- * Returns a list containing all elements of original collection and then all elements of the given [collection].
+ * Returns a list containing all elements of original collection and then all elements of the given [array].
  */
 public fun <T> Array<out T>.plus(array: Array<out T>): List<T> {
     val answer = ArrayList<T>(size() + array.size())
@@ -637,7 +637,7 @@ public fun <T> Array<out T>.plus(array: Array<out T>): List<T> {
 }
 
 /**
- * Returns a list containing all elements of original collection and then all elements of the given [collection].
+ * Returns a list containing all elements of original collection and then all elements of the given [array].
  */
 public fun BooleanArray.plus(array: Array<out Boolean>): List<Boolean> {
     val answer = ArrayList<Boolean>(size() + array.size())
@@ -647,7 +647,7 @@ public fun BooleanArray.plus(array: Array<out Boolean>): List<Boolean> {
 }
 
 /**
- * Returns a list containing all elements of original collection and then all elements of the given [collection].
+ * Returns a list containing all elements of original collection and then all elements of the given [array].
  */
 public fun ByteArray.plus(array: Array<out Byte>): List<Byte> {
     val answer = ArrayList<Byte>(size() + array.size())
@@ -657,7 +657,7 @@ public fun ByteArray.plus(array: Array<out Byte>): List<Byte> {
 }
 
 /**
- * Returns a list containing all elements of original collection and then all elements of the given [collection].
+ * Returns a list containing all elements of original collection and then all elements of the given [array].
  */
 public fun CharArray.plus(array: Array<out Char>): List<Char> {
     val answer = ArrayList<Char>(size() + array.size())
@@ -667,7 +667,7 @@ public fun CharArray.plus(array: Array<out Char>): List<Char> {
 }
 
 /**
- * Returns a list containing all elements of original collection and then all elements of the given [collection].
+ * Returns a list containing all elements of original collection and then all elements of the given [array].
  */
 public fun DoubleArray.plus(array: Array<out Double>): List<Double> {
     val answer = ArrayList<Double>(size() + array.size())
@@ -677,7 +677,7 @@ public fun DoubleArray.plus(array: Array<out Double>): List<Double> {
 }
 
 /**
- * Returns a list containing all elements of original collection and then all elements of the given [collection].
+ * Returns a list containing all elements of original collection and then all elements of the given [array].
  */
 public fun FloatArray.plus(array: Array<out Float>): List<Float> {
     val answer = ArrayList<Float>(size() + array.size())
@@ -687,7 +687,7 @@ public fun FloatArray.plus(array: Array<out Float>): List<Float> {
 }
 
 /**
- * Returns a list containing all elements of original collection and then all elements of the given [collection].
+ * Returns a list containing all elements of original collection and then all elements of the given [array].
  */
 public fun IntArray.plus(array: Array<out Int>): List<Int> {
     val answer = ArrayList<Int>(size() + array.size())
@@ -697,7 +697,7 @@ public fun IntArray.plus(array: Array<out Int>): List<Int> {
 }
 
 /**
- * Returns a list containing all elements of original collection and then all elements of the given [collection].
+ * Returns a list containing all elements of original collection and then all elements of the given [array].
  */
 public fun LongArray.plus(array: Array<out Long>): List<Long> {
     val answer = ArrayList<Long>(size() + array.size())
@@ -707,7 +707,7 @@ public fun LongArray.plus(array: Array<out Long>): List<Long> {
 }
 
 /**
- * Returns a list containing all elements of original collection and then all elements of the given [collection].
+ * Returns a list containing all elements of original collection and then all elements of the given [array].
  */
 public fun ShortArray.plus(array: Array<out Short>): List<Short> {
     val answer = ArrayList<Short>(size() + array.size())
@@ -717,7 +717,7 @@ public fun ShortArray.plus(array: Array<out Short>): List<Short> {
 }
 
 /**
- * Returns a list containing all elements of original collection and then all elements of the given [collection].
+ * Returns a list containing all elements of original collection and then all elements of the given [array].
  */
 public fun <T> Iterable<T>.plus(array: Array<out T>): List<T> {
     val answer = ArrayList<T>(collectionSizeOrDefault(10) + array.size())

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

@@ -19,6 +19,9 @@ public interface Stream<out T> {
  */
 public interface Sequence<out T> : Stream<T>
 
+/**
+ * Converts a stream to a sequence.
+ */
 public fun<T> Stream<T>.toSequence(): Sequence<T> = object : Sequence<T> {
     override fun iterator(): Iterator<T> = this@toSequence.iterator()
 }

libraries/stdlib/src/kotlin/dom/Dom.kt

@@ -71,7 +71,7 @@ public fun Element?.childElements(name: String): List<Element> {
     return children().filter<Node>{ it.nodeType == Node.ELEMENT_NODE && it.nodeName == name }.map { it as Element }
 }
 
-/** The descendent elements of this document */
+/** The descendant elements of this document */
 public val Document?.elements: List<Element>
     get() = this?.getElementsByTagName("*").toElementList()
 
@@ -233,7 +233,7 @@ private class ElementListAsList(private val nodeList: NodeList) : AbstractList<E
 
 }
 
-/** Returns an [[Iterator]] over the next siblings of this node */
+/** Returns an [Iterator] over the next siblings of this node */
 public fun Node.nextSiblings(): Iterable<Node> = NextSiblings(this)
 
 private class NextSiblings(private var node: Node) : Iterable<Node> {
@@ -250,7 +250,7 @@ private class NextSiblings(private var node: Node) : Iterable<Node> {
     }
 }
 
-/** Returns an [[Iterator]] over the next siblings of this node */
+/** Returns an [Iterator] over the next siblings of this node */
 public fun Node.previousSiblings(): Iterable<Node> = PreviousSiblings(this)
 
 private class PreviousSiblings(private var node: Node) : Iterable<Node> {

libraries/stdlib/src/kotlin/dom/DomJVM.kt

@@ -123,10 +123,10 @@ public val Node.innerHTML: String
 public val NodeList.outerHTML: String
     get() = toList().map { it.innerHTML }.join("")
 
-/** Returns an [[Iterator]] of all the next [[Element]] siblings */
+/** Returns an [Iterator] of all the next [Element] siblings */
 public fun Node.nextElements(): List<Element> = nextSiblings().filterIsInstance(javaClass<Element>())
 
-/** Returns an [[Iterator]] of all the previous [[Element]] siblings */
+/** Returns an [Iterator] of all the previous [Element] siblings */
 public fun Node.previousElements(): List<Element> = previousSiblings().filterIsInstance(javaClass<Element>())
 
 
@@ -157,14 +157,14 @@ public fun createDocument(builderFactory: DocumentBuilderFactory = defaultDocume
 }
 
 /**
- * Returns the default [[DocumentBuilderFactory]]
+ * Returns the default [DocumentBuilderFactory]
  */
 public fun defaultDocumentBuilderFactory(): DocumentBuilderFactory {
     return DocumentBuilderFactory.newInstance()!!
 }
 
 /**
- * Returns the default [[DocumentBuilder]]
+ * Returns the default [DocumentBuilder]
  */
 public fun defaultDocumentBuilder(builderFactory: DocumentBuilderFactory = defaultDocumentBuilderFactory()): DocumentBuilder {
     return builderFactory.newDocumentBuilder()
@@ -219,7 +219,7 @@ public fun Node.toXmlString(xmlDeclaration: Boolean): String {
     return writer.toString()
 }
 
-/** Converts the node to an XML String and writes it to the given [[Writer]] */
+/** Converts the node to an XML String and writes it to the given [Writer] */
 public fun Node.writeXmlString(writer: Writer, xmlDeclaration: Boolean): Unit {
     val transformer = createTransformer()
     transformer.setOutputProperty(OutputKeys.OMIT_XML_DECLARATION, if (xmlDeclaration) "no" else "yes")

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

@@ -16,6 +16,9 @@ private fun constructMessage(file: File, other: File?, reason: String?): String
 
 /**
  * A base exception class for file system exceptions.
+ * @property file the file on which the failed operation was performed.
+ * @property other the second file involved in the operation, if any (for example, the target of a copy or move)
+ * @property reason the description of the error
  */
 open public class FileSystemException(public val file: File,
                                       public val other: File? = null,

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

@@ -77,9 +77,23 @@ public val File.root: File?
         return if (name.length() > 0) File(name) else null
     }
 
+/**
+ * Represents the path to a file as a collection of directories.
+ *
+ * @property rootName the name of the root of the path (for example, `/` or `C:`).
+ * @property fileList the list of [File] objects representing every directory in the path to the file,
+ *     up to an including the file itself.
+ */
 public data class FilePathComponents(public val rootName: String, public val fileList: List<File>) {
+    /**
+     * Returns the number of elements in the path to the file.
+     */
     public fun size(): Int = fileList.size()
 
+    /**
+     * Returns a sub-path of the path, starting with the directory at the specified [beginIndex] and up
+     * to the specified [endIndex].
+     */
     public fun subPath(beginIndex: Int, endIndex: Int): File {
         if (beginIndex < 0 || beginIndex > endIndex || endIndex > size())
             throw IllegalArgumentException()
@@ -88,6 +102,10 @@ public data class FilePathComponents(public val rootName: String, public val fil
     }
 }
 
+/**
+ * Splits the file into path components (the names of containing directories and the name of the file
+ * itself) and returns the resulting collection of components.
+ */
 public fun File.filePathComponents(): FilePathComponents {
     val path = separatorsToSystem()
     val rootName = path.getRootName()

libraries/tools/kotlin-stdlib-gen/src/templates/Generators.kt

@@ -60,7 +60,7 @@ fun generators(): List<GenericFunction> {
 
     templates add f("plus(array: Array<out T>)") {
         exclude(Strings, Sequences)
-        doc { "Returns a list containing all elements of original collection and then all elements of the given [collection]." }
+        doc { "Returns a list containing all elements of original collection and then all elements of the given [array]." }
         returns("List<T>")
         body {
             """
@@ -108,8 +108,8 @@ fun generators(): List<GenericFunction> {
         doc {
             """
             Splits original collection into pair of collections,
-            where *first* collection contains elements for which [predicate] yielded [true],
-            while *second* collection contains elements for which [predicate] yielded [false].
+            where *first* collection contains elements for which [predicate] yielded `true`,
+            while *second* collection contains elements for which [predicate] yielded `false`.
             """
         }
         // TODO: Sequence variant