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

sdk/lib/io/link.dart

 // Copyright (c) 2013, 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;
 
 /**
  * [Link] objects are references to filesystem links.
  *
  */
@@ skipping 16 matching lines @@
   Future<bool> exists();
 
   /**
    * Synchronously checks if the link exists. The link may exist, even if
    * its target is missing or deleted.
    */
   bool existsSync();
 
   /**
    * 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);
 
   /**
    * Synchronously create the link. Calling [createSync] on an existing link
    * will throw an exception.
    *
    * 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.
    */
   void createSync(String target);
 
   /**
    * Synchronously updates the link. Calling [updateSync] on a non-existing link
    * will throw an exception.
    *
    * If [linkRelative] is true, the target argument should be a relative path,
    * and the link will interpret the target as a path relative to the link's
    * directory.
    *
    * On the Windows platform, this will only work with directories, and the
    * target directory must exist.
    */
   void updateSync(String target, {bool linkRelative: false });
 
   /**
    * 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();
 
   /**
    * Gets the target of the link. Returns a future that completes with
    * the path to the target.
    *
    * If the returned target is a relative path, it is relative to the
    * directory containing the link.
    *
@@ skipping 106 matching lines @@
   }
 
   String targetSync() {
     var result = _File._linkTarget(path);
     throwIfError(result, "Cannot read link '$path'");
     return result;
   }
 
   static throwIfError(Object result, String msg) {
     if (result is OSError) {
-      throw new FileIOException(msg, result);
+      throw new LinkIOException(msg, result);
     }
   }
 
   bool _isErrorResponse(response) {
     return response is List && response[0] != _SUCCESS_RESPONSE;
   }
 
   void _ensureFileService() {
     if (_fileService == null) {
       _fileService = _FileUtils._newServicePort();
     }
   }
 
   _exceptionFromResponse(response, String message) {
     assert(_isErrorResponse(response));
     switch (response[_ERROR_RESPONSE_ERROR_TYPE]) {
       case _ILLEGAL_ARGUMENT_RESPONSE:
         return new ArgumentError();
       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");
     }
   }
 }
 
 
 class LinkIOException implements Exception {
   const LinkIOException([String this.message = "",
                          String this.path = "",
@@ skipping 14 matching lines @@
       if (path != null) {
         sb.write(", path = $path");
       }
     }
     return sb.toString();
   }
   final String message;
   final String path;
   final OSError osError;
 }