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

sdk/lib/io/file.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;
 
 /**
  * FileMode describes the modes in which a file can be opened.
  */
 class FileMode {
@@ skipping 58 matching lines @@
    * Synchronously create the file. Existing files are left untouched
    * by [createSync]. Calling [createSync] on an existing file might fail
    * if there are restrictive permissions on the file.
    *
    * Throws a [FileIOException] if the operation fails.
    */
   void createSync();
 
   /**
    * 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.
    */
   void deleteSync();
 
   /**
    * Get a [Directory] object for the directory containing this
    * file. Returns a [:Future<Directory>:] that completes with the
    * directory.
    */
@@ skipping 425 matching lines @@
         sb.write(" ($osError)");
       }
     } else if (osError != null) {
       sb.write(": osError");
     }
     return sb.toString();
   }
   final String message;
   final OSError osError;
 }