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..b1eca17dd6180bd502af8e962d51712cec950f04 100644
--- a/sdk/lib/io/directory.dart
+++ b/sdk/lib/io/directory.dart
@@ -87,10 +87,16 @@ 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 any file system object.
    *
    * Returns a [:Future<Directory>:] that completes with this
    * directory when the deletion is done. If the directory cannot be
@@ -104,7 +110,12 @@ 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 any file system object.
    *
    * Throws an exception if the directory cannot be deleted.
    */
@@ -135,9 +146,14 @@ 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 working links are reported as
+   * directories or files, depending on
+   * their type, and links to directories are recursed into.
+   * Broken links are reported as [Link] objects,
+   *
    * The result is a stream of [FileSystemEntity] objects
    * for the directories, files, and links.
    */
@@ -149,9 +165,14 @@ 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 working links are reported as
+   * directories or files, depending on
+   * their type, and links to directories are recursed into.
+   * Broken links are reported as [Link] objects,
+   *
    * Returns a [List] containing [FileSystemEntity] objects for the
    * directories, files, and links.
    */