Merge pull request #677 from JetBrains/rr/yole/stdlib-docs

stdlib doc-related cleanup

.idea/ant.xml

@@ -16,7 +16,7 @@
     <buildFile url="file://$PROJECT_DIR$/libraries/build-docs.xml">
       <maximumHeapSize value="1024" />
       <properties>
-        <property name="dokka.path" value="../../dokka/out/artifacts" />
+        <property name="dokka.path" value="../../dokka" />
       </properties>
     </buildFile>
   </component>

libraries/build-docs.xml

@@ -2,7 +2,12 @@
     <!-- Generates the standard library documentation using Dokka. -->
     <typedef resource="dokka-antlib.xml">
         <classpath>
-            <pathelement path="${dokka.path}/dokka.jar"/>
+            <fileset dir="${dokka.path}/lib">
+                <include name="*.jar"/>
+            </fileset>
+
+            <!-- used for running locally -->
+            <pathelement path="${dokka.path}/out/artifacts/dokka.jar"/>
         </classpath>
     </typedef>
 

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/ArraysJVM.kt

@@ -9,48 +9,48 @@ import kotlin.jvm.internal.Intrinsic
 /**
  * Returns an array containing the specified elements.
  */
-[Intrinsic("kotlin.arrays.array")] public fun <reified T> arrayOf(vararg t : T) : Array<T> = t as Array<T>
+@Intrinsic("kotlin.arrays.array") public fun <reified T> arrayOf(vararg t : T) : Array<T> = t as Array<T>
 
 // "constructors" for primitive types array
 /**
  * Returns an array containing the specified [Double] numbers.
  */
-[Intrinsic("kotlin.arrays.array")] public fun doubleArrayOf(vararg content : Double) : DoubleArray    = content
+@Intrinsic("kotlin.arrays.array") public fun doubleArrayOf(vararg content : Double) : DoubleArray    = content
 
 /**
  * Returns an array containing the specified [Float] numbers.
  */
-[Intrinsic("kotlin.arrays.array")] public fun floatArrayOf(vararg content : Float) : FloatArray       = content
+@Intrinsic("kotlin.arrays.array") public fun floatArrayOf(vararg content : Float) : FloatArray       = content
 
 /**
  * Returns an array containing the specified [Long] numbers.
  */
-[Intrinsic("kotlin.arrays.array")] public fun longArrayOf(vararg content : Long) : LongArray          = content
+@Intrinsic("kotlin.arrays.array") public fun longArrayOf(vararg content : Long) : LongArray          = content
 
 /**
  * Returns an array containing the specified [Int] numbers.
  */
-[Intrinsic("kotlin.arrays.array")] public fun intArrayOf(vararg content : Int) : IntArray             = content
+@Intrinsic("kotlin.arrays.array") public fun intArrayOf(vararg content : Int) : IntArray             = content
 
 /**
  * Returns an array containing the specified characters.
  */
-[Intrinsic("kotlin.arrays.array")] public fun charArrayOf(vararg content : Char) : CharArray          = content
+@Intrinsic("kotlin.arrays.array") public fun charArrayOf(vararg content : Char) : CharArray          = content
 
 /**
  * Returns an array containing the specified [Short] numbers.
  */
-[Intrinsic("kotlin.arrays.array")] public fun shortArrayOf(vararg content : Short) : ShortArray       = content
+@Intrinsic("kotlin.arrays.array") public fun shortArrayOf(vararg content : Short) : ShortArray       = content
 
 /**
  * Returns an array containing the specified [Byte] numbers.
  */
-[Intrinsic("kotlin.arrays.array")] public fun byteArrayOf(vararg content : Byte) : ByteArray          = content
+@Intrinsic("kotlin.arrays.array") public fun byteArrayOf(vararg content : Byte) : ByteArray          = content
 
 /**
  * Returns an array containing the specified boolean values.
  */
-[Intrinsic("kotlin.arrays.array")] public fun booleanArrayOf(vararg content : Boolean) : BooleanArray = content
+@Intrinsic("kotlin.arrays.array") public fun booleanArrayOf(vararg content : Boolean) : BooleanArray = content
 
 
 /**

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/stdlib/src/kotlin/jvm/internal/unsafe/monitor.kt

@@ -19,9 +19,9 @@ package kotlin.jvm.internal.unsafe
 import kotlin.jvm.internal.Intrinsic
 
 /** @suppress */
-[Intrinsic("kotlin.jvm.internal.unsafe.monitorEnter")]
+@Intrinsic("kotlin.jvm.internal.unsafe.monitorEnter")
 public fun monitorEnter(monitor: Any): Unit = throw UnsupportedOperationException("This function can only be used privately")
 
 /** @suppress */
-[Intrinsic("kotlin.jvm.internal.unsafe.monitorExit")]
+@Intrinsic("kotlin.jvm.internal.unsafe.monitorExit")
 public fun monitorExit(monitor: Any): Unit = throw UnsupportedOperationException("This function can only be used privately")

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

@@ -30,13 +30,13 @@ public annotation class throws(public vararg val exceptionClasses: KClass<out Th
 /**
  * Returns the runtime Java class of this object.
  */
-[Intrinsic("kotlin.javaClass.property")] public val <T: Any> T.javaClass : Class<T>
+@Intrinsic("kotlin.javaClass.property") public val <T: Any> T.javaClass : Class<T>
     get() = (this as java.lang.Object).getClass() as Class<T>
 
 /**
  * Returns the Java class for the specified type.
  */
-[Intrinsic("kotlin.javaClass.function")] public fun <reified T: Any> javaClass(): Class<T> = null as Class<T>
+@Intrinsic("kotlin.javaClass.function") public fun <reified T: Any> javaClass(): Class<T> = null as Class<T>
 
 /**
  * Executes the given function [block] while holding the monitor of the given object [lock].

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