dart:io | Add documentation changes to Link, File and Directory delete methods.

sdk/lib/io/directory.dart

Index: sdk/lib/io/directory.dart
diff --git a/sdk/lib/io/directory.dart b/sdk/lib/io/directory.dart
index f9bcff5c17a2a629e0a17ba2f490c8952e32fead..f66bf49065846b3d5f8ce123169b2f6eabf6414b 100644
--- a/sdk/lib/io/directory.dart
+++ b/sdk/lib/io/directory.dart
@@ -87,10 +87,17 @@ abstract class Directory extends FileSystemEntity {
   /**
    * Deletes this directory.
    *
-   * If [recursive] is false, the directory must be empty.
+   * If [recursive] is false, the directory must be empty.  Only directories
+   * and links to directories will be deleted.
    *
    * If [recursive] is true, this directory and all sub-directories
-   * and files in the directories are deleted.
+   * and files in the directories are deleted. Links are not followed
+   * when deleting recursively. Only the link is deleted, not its target.
+   *
+   * If [recursive] is true, the target is deleted even if it is a file, or
+   * a link to a file, not only if it is a directory.  This behavior allows
+   * [delete] to be used to unconditionally delete the file system object at

[Anders Johnsen, 2013/04/09 16:34:36]

'delete any file system object'

[Bill Hesse, 2013/04/10 08:07:07]

Done.

+   * a given location.

[Anders Johnsen, 2013/04/09 16:34:36]

location or path?

    *
    * Returns a [:Future<Directory>:] that completes with this
    * directory when the deletion is done. If the directory cannot be
@@ -104,7 +111,13 @@ abstract class Directory extends FileSystemEntity {
    * If [recursive] is false, the directory must be empty.
    *
    * If [recursive] is true, this directory and all sub-directories
-   * and files in the directories are deleted.
+   * and files in the directories are deleted. Links are not followed
+   * when deleting recursively. Only the link is deleted, not its target.
+   *
+   * If [recursive] is true, the target is deleted even if it is a file, or
+   * a link to a file, not only if it is a directory.  This behavior allows
+   * [delete] to be used to unconditionally delete the file system object at
+   * a given location.
    *
    * Throws an exception if the directory cannot be deleted.
    */
@@ -135,9 +148,13 @@ abstract class Directory extends FileSystemEntity {
    * Optionally recurses into sub-directories.
    *
    * If [followLinks] is false, then any symbolic links found
-   * are reported as links, rather than as directories or files,
+   * are reported as [Link] objects, rather than as directories or files,
    * and are not recursed into.
    *
+   * If [followLinks] is true, then broken links are reported as [Link] objects,

[Anders Johnsen, 2013/04/09 16:34:36]

I think the broken-links part should be in the end - it's a rare thing, and not
the most important part of this sentence.

[Bill Hesse, 2013/04/10 08:07:07]

Done.

+   * but working links are reported as a directories or files, depending on
+   * their type, and links to directories are recursed into.
+   *
    * The result is a stream of [FileSystemEntity] objects
    * for the directories, files, and links.
    */
@@ -149,9 +166,13 @@ abstract class Directory extends FileSystemEntity {
    * Optionally recurses into sub-directories.
    *
    * If [followLinks] is false, then any symbolic links found
-   * are reported as links, rather than as directories or files,
+   * are reported as [Link] objects, rather than as directories or files,
    * and are not recursed into.
    *
+   * If [followLinks] is true, then broken links are reported as [Link] objects,
+   * but working links are reported as directories or files, depending on
+   * their type, and links to directories are recursed into.
+   *
    * Returns a [List] containing [FileSystemEntity] objects for the
    * directories, files, and links.
    */