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

sdk/lib/io/directory.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.io;
 
 /**
  * [Directory] objects are used for working with directories.
  */
 abstract class Directory extends FileSystemEntity {
@@ skipping 69 matching lines @@
    * current path. The path is used as a template, and additional
    * characters are appended to it to make a unique temporary directory name.
    * If the path is the empty string, a default system temp directory and name
    * are used for the template. Returns the newly created temporary directory.
    */
   Directory createTempSync();
 
   /**
    * 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
    * deleted, the future completes with an exception.
    */
   Future<Directory> delete({recursive: false});
 
   /**
    * Synchronously deletes this directory.
    *
    * 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.
    */
   void deleteSync({recursive: false});
 
   /**
    * Renames this directory. Returns a [:Future<Directory>:] that completes
    * with a [Directory] instance for the renamed directory.
    *
    * If newPath identifies an existing directory, that directory is
@@ skipping 10 matching lines @@
    * replaced. If newPath identifies an existing file the operation
    * fails and an exception is thrown.
    */
   Directory renameSync(String newPath);
 
   /**
    * Lists the sub-directories and files of this [Directory].
    * 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.
    */
   Stream<FileSystemEntity> list({bool recursive: false,
                                  bool followLinks: true});
 
   /**
    * Lists the sub-directories and files of this [Directory].
    * 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.
    */
   List<FileSystemEntity> listSync({bool recursive: false,
                                    bool followLinks: true});
 
   /**
    * Returns a human readable string for this Directory instance.
    */
   String toString();
@@ skipping 25 matching lines @@
       if (path != null) {
         sb.write(", path = $path");
       }
     }
     return sb.toString();
   }
   final String message;
   final String path;
   final OSError osError;
 }