correct some errors and omissions in stdlib doc comments

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()