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

BUG=

Review URL: https://codereview.chromium.org//13862003

git-svn-id: https://dart.googlecode.com/svn/branches/bleeding_edge/dart@21183 260f80e4-7a28-3924-810f-c04153c831b5

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.
    */

sdk/lib/io/file.dart

@@ -76,12 +76,14 @@ abstract class File extends FileSystemEntity {
 
   /**
    * Delete the file. Returns a [:Future<File>:] that completes with
-   * the file when it has been deleted.
+   * the file when it has been deleted. Only a file or a link to a file
+   * can be deleted with this method, not a directory or a broken link.
    */
   Future<File> delete();
 
   /**
-   * Synchronously delete the file.
+   * Synchronously delete the file. Only a file or a link to a file
+   * can be deleted with this method, not a directory or a broken link.
    *
    * Throws a [FileIOException] if the operation fails.
    */

sdk/lib/io/link.dart

@@ -34,13 +34,17 @@ abstract class Link extends FileSystemEntity {
 
   /**
    * Creates a symbolic link. Returns a [:Future<Link>:] that completes with
-   * the link when it has been created. If the link exists, the function
+   * the link when it has been created. If the link exists,
    * the future will complete with an error.
    *
    * On the Windows platform, this will only work with directories, and the
    * target directory must exist. The link will be created as a Junction.
    * Only absolute links will be created, and relative paths to the target
    * will be converted to absolute paths.
+   *
+   * On other platforms, the posix symlink() call is used to make a symbolic
+   * link containing the string [target].  If [target] is a relative path,
+   * it will be interpreted relative to the directory containing the link.
    */
   Future<Link> create(String target);
 
@@ -52,6 +56,10 @@ abstract class Link extends FileSystemEntity {
    * target directory must exist. The link will be created as a Junction.
    * Only absolute links will be created, and relative paths to the target
    * will be converted to absolute paths.
+   *
+   * On other platforms, the posix symlink() call is used to make a symbolic
+   * link containing the string [target].  If [target] is a relative path,
+   * it will be interpreted relative to the directory containing the link.
    */
   void createSync(String target);
 
@@ -70,14 +78,18 @@ abstract class Link extends FileSystemEntity {
 
   /**
    * Deletes the link. Returns a [:Future<Link>:] that completes with
-   * the link when it has been deleted.  This does not delete, or otherwise
-   * affect, the target of the link.
+   * the link when it has been deleted. This does not delete, or otherwise
+   * affect, the target of the link. It also works on broken links, but if
+   * the link does not exist or is not actually a link, it completes the
+   * future with a LinkIOException.
    */
   Future<Link> delete();
 
   /**
    * Synchronously deletes the link. This does not delete, or otherwise
-   * affect, the target of the link.
+   * affect, the target of the link.  It also works on broken links, but if
+   * the link does not exist or is not actually a link, it throws a
+   * LinkIOException.
    */
   void deleteSync();
 
@@ -204,7 +216,7 @@ class _Link extends FileSystemEntity implements Link {
 
   static throwIfError(Object result, String msg) {
     if (result is OSError) {
-      throw new FileIOException(msg, result);
+      throw new LinkIOException(msg, result);
     }
   }
 
@@ -226,9 +238,7 @@ class _Link extends FileSystemEntity implements Link {
       case _OSERROR_RESPONSE:
         var err = new OSError(response[_OSERROR_RESPONSE_MESSAGE],
                               response[_OSERROR_RESPONSE_ERROR_CODE]);
-        return new FileIOException(message, err);
-      case _FILE_CLOSED_RESPONSE:
-        return new FileIOException("File closed");
+        return new LinkIOException(message, err);
       default:
         return new Exception("Unknown error");
     }