From 495967a573d3246bbba47d2ae45d0f0a4cc02989 Mon Sep 17 00:00:00 2001
From: Denis Mekhanikov <dmekhanikov@gmail.com>
Date: Tue, 21 Oct 2014 20:08:01 +0400
Subject: [PATCH] stdlib: fix documentation for some IO functions

---
 libraries/stdlib/src/kotlin/io/Files.kt | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/libraries/stdlib/src/kotlin/io/Files.kt b/libraries/stdlib/src/kotlin/io/Files.kt
index dfe7c9bf6ee..bfd08feaa4f 100644
--- a/libraries/stdlib/src/kotlin/io/Files.kt
+++ b/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 {