stdlib: fix documentation for some IO functions

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

@@ -5,7 +5,8 @@ import java.nio.charset.*
 import java.util.*
 
 /**
- * Recursively process this file and all children with the given block
+ * 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.
  */
 public fun File.recurse(block: (File) -> Unit): Unit {
     block(this)
@@ -13,7 +14,7 @@ public fun File.recurse(block: (File) -> Unit): Unit {
 }
 
 /**
- * Returns this if the file is a directory or the parent if its a file inside a directory
+ * Returns this if the 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 getParentFile()!!
@@ -37,7 +38,7 @@ public val File.path: String
     get() = getPath()
 
 /**
- * Returns true if the file ends with the given extension
+ * Returns file's extension or an empty string if it doesn't have one
  */
 public val File.extension: String
     get() {
@@ -52,7 +53,7 @@ public fun File.isDescendant(file: File): Boolean {
 }
 
 /**
- * Returns the relative path of the given descendant of this file if its a descendant
+ * Returns the relative path of the given descendant of this file if it is a descendant
  */
 public fun File.relativePath(descendant: File): String {
     val prefix = directory.canonicalPath
@@ -82,7 +83,8 @@ public fun File.copyTo(file: File, bufferSize: Int = defaultBufferSize): Long {
 }
 
 /**
- * Returns an array of files and directories in the directory that satisfy the specified filter.
+ * Returns an array of files and directories in the directory that satisfy the specified filter
+ * or null if this file does not denote a directory.
  */
 public fun File.listFiles(filter: (file: File) -> Boolean): Array<File>? = listFiles(
         object : FileFilter {