Document FileSystemEntity.delete when the type of object on the file system does not match the FileSystemEntity type.

Bug:https://github.com/dart-lang/sdk/issues/53917
Change-Id: I71d95e36c193314afa1872de6e34b1b5a41d7bd9
CoreLibraryReviewExempt: Documentation-only change
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/335328
Commit-Queue: Brian Quinlan <bquinlan@google.com>
Reviewed-by: Alexander Aprelev <aam@google.com>

sdk/lib/io/directory.dart

@@ -257,6 +257,52 @@ abstract interface class Directory implements FileSystemEntity {
   /// fails and a [FileSystemException] is thrown.
   Directory renameSync(String newPath);
 
+  /// Deletes this [Directory].
+  ///
+  /// If [recursive] is `false`:
+  ///
+  ///  * If [path] corresponds to an empty directory, then that directory is
+  ///    deleted. If [path] corresponds to a link, and that link resolves
+  ///    to a directory, then the link at [path] will be deleted. In all
+  ///    other cases, [delete] completes with a [FileSystemException].
+  ///
+  /// If [recursive] is `true`:
+  ///
+  ///  * The [FileSystemEntity] at [path] is deleted regardless of type. If
+  ///    [path] corresponds to a file or link, then that file or link is
+  ///    deleted. If [path] corresponds to a directory, then it and all
+  ///    sub-directories and files in those directories are deleted. Links
+  ///    are not followed when deleting recursively. Only the link is deleted,
+  ///    not its target. This behavior allows [delete] to be used to
+  ///    unconditionally delete any file system object.
+  ///
+  /// If this [Directory] cannot be deleted, then [delete] completes with a
+  /// [FileSystemException].
+  Future<FileSystemEntity> delete({bool recursive = false});
+
+  /// Synchronously deletes this [Directory].
+  ///
+  /// If [recursive] is `false`:
+  ///
+  ///  * If [path] corresponds to an empty directory, then that directory is
+  ///    deleted. If [path] corresponds to a link, and that link resolves
+  ///    to a directory, then the link at [path] will be deleted. In all
+  ///    other cases, [delete] throws a [FileSystemException].
+  ///
+  /// If [recursive] is `true`:
+  ///
+  ///  * The [FileSystemEntity] at [path] is deleted regardless of type. If
+  ///    [path] corresponds to a file or link, then that file or link is
+  ///    deleted. If [path] corresponds to a directory, then it and all
+  ///    sub-directories and files in those directories are deleted. Links
+  ///    are not followed when deleting recursively. Only the link is deleted,
+  ///    not its target. This behavior allows [delete] to be used to
+  ///    unconditionally delete any file system object.
+  ///
+  /// If this [Directory] cannot be deleted, then [delete] throws a
+  /// [FileSystemException].
+  void deleteSync({bool recursive = false});
+
   /// A [Directory] whose path is the absolute path of [this].
   ///
   /// The absolute path is computed by prefixing

sdk/lib/io/file.dart

@@ -302,6 +302,52 @@ abstract interface class File implements FileSystemEntity {
   /// operation throws a [FileSystemException].
   File renameSync(String newPath);
 
+  /// Deletes this [File].
+  ///
+  /// If [recursive] is `false`:
+  ///
+  ///  * If [path] corresponds to a regular file, named pipe or socket, then
+  ///    that path is deleted. If [path] corresponds to a link, and that link
+  ///    resolves to a file, then the link at [path] will be deleted. In all
+  ///    other cases, [delete] completes with a [FileSystemException].
+  ///
+  /// If [recursive] is `true`:
+  ///
+  ///  * The [FileSystemEntity] at [path] is deleted regardless of type. If
+  ///    [path] corresponds to a file or link, then that file or link is
+  ///    deleted. If [path] corresponds to a directory, then it and all
+  ///    sub-directories and files in those directories are deleted. Links
+  ///    are not followed when deleting recursively. Only the link is deleted,
+  ///    not its target. This behavior allows [delete] to be used to
+  ///    unconditionally delete any file system object.
+  ///
+  /// If this [File] cannot be deleted, then [delete] completes with a
+  /// [FileSystemException].
+  Future<FileSystemEntity> delete({bool recursive = false});
+
+  /// Synchronously deletes this [File].
+  ///
+  /// If [recursive] is `false`:
+  ///
+  ///  * If [path] corresponds to a regular file, named pipe or socket, then
+  ///    that path is deleted. If [path] corresponds to a link, and that link
+  ///    resolves to a file, then the link at [path] will be deleted. In all
+  ///    other cases, [delete] throws a [FileSystemException].
+  ///
+  /// If [recursive] is `true`:
+  ///
+  ///  * The [FileSystemEntity] at [path] is deleted regardless of type. If
+  ///    [path] corresponds to a file or link, then that file or link is
+  ///    deleted. If [path] corresponds to a directory, then it and all
+  ///    sub-directories and files in those directories are deleted. Links
+  ///    are not followed when deleting recursively. Only the link is deleted,
+  ///    not its target. This behavior allows [delete] to be used to
+  ///    unconditionally delete any file system object.
+  ///
+  /// If this [File] cannot be deleted, then [delete] throws a
+  /// [FileSystemException].
+  void deleteSync({bool recursive = false});
+
   /// Copies this file.
   ///
   /// If [newPath] is a relative path, it is resolved against

sdk/lib/io/file_system_entity.dart

@@ -388,37 +388,21 @@ abstract class FileSystemEntity {
 
   /// Deletes this [FileSystemEntity].
   ///
-  /// If the [FileSystemEntity] is a directory, and if [recursive] is `false`,
-  /// the directory must be empty. Otherwise, if [recursive] is true, the
-  /// directory and all sub-directories and files in the directories are
-  /// deleted. Links are not followed when deleting recursively. Only the link
-  /// is deleted, not its target.
+  /// The exact details vary according to the [FileSystemEntity]:
   ///
-  /// If [recursive] is true, the [FileSystemEntity] is deleted even if the type
-  /// of the [FileSystemEntity] doesn't match the content of the file system.
-  /// This behavior allows [delete] to be used to unconditionally delete any file
-  /// system object.
-  ///
-  /// Returns a `Future<FileSystemEntity>` that completes with this
-  /// [FileSystemEntity] when the deletion is done. If the [FileSystemEntity]
-  /// cannot be deleted, the future completes with an exception.
+  ///   * [Directory.delete]
+  ///   * [File.delete]
+  ///   * [Link.delete]
   Future<FileSystemEntity> delete({bool recursive = false}) =>
       _delete(recursive: recursive);
 
   /// Synchronously deletes this [FileSystemEntity].
   ///
-  /// If the [FileSystemEntity] is a directory, and if [recursive] is false,
-  /// the directory must be empty. Otherwise, if [recursive] is true, the
-  /// directory and all sub-directories and files in the directories are
-  /// deleted. Links are not followed when deleting recursively. Only the link
-  /// is deleted, not its target.
+  /// The exact details vary according to the [FileSystemEntity]:
   ///
-  /// If [recursive] is true, the [FileSystemEntity] is deleted even if the type
-  /// of the [FileSystemEntity] doesn't match the content of the file system.
-  /// This behavior allows [deleteSync] to be used to unconditionally delete any
-  /// file system object.
-  ///
-  /// Throws an exception if the [FileSystemEntity] cannot be deleted.
+  ///   * [Directory.deleteSync]
+  ///   * [File.deleteSync]
+  ///   * [Link.deleteSync]
   void deleteSync({bool recursive = false}) =>
       _deleteSync(recursive: recursive);
 

sdk/lib/io/link.dart

@@ -152,6 +152,48 @@ abstract interface class Link implements FileSystemEntity {
   /// [FileSystemException] is thrown.
   Link renameSync(String newPath);
 
+  /// Deletes this [Link].
+  ///
+  /// If [recursive] is `false`:
+  ///
+  ///  * If [path] corresponds to a link then that path is deleted. Otherwise,
+  ///    [delete] completes with a [FileSystemException].
+  ///
+  /// If [recursive] is `true`:
+  ///
+  ///  * The [FileSystemEntity] at [path] is deleted regardless of type. If
+  ///    [path] corresponds to a file or link, then that file or link is
+  ///    deleted. If [path] corresponds to a directory, then it and all
+  ///    sub-directories and files in those directories are deleted. Links
+  ///    are not followed when deleting recursively. Only the link is deleted,
+  ///    not its target. This behavior allows [delete] to be used to
+  ///    unconditionally delete any file system object.
+  ///
+  /// If this [Link] cannot be deleted, then [delete] completes with a
+  /// [FileSystemException].
+  Future<FileSystemEntity> delete({bool recursive = false});
+
+  /// Synchronously deletes this [Link].
+  ///
+  /// If [recursive] is `false`:
+  ///
+  ///  * If [path] corresponds to a link then that path is deleted. Otherwise,
+  ///    [delete] throws a [FileSystemException].
+  ///
+  /// If [recursive] is `true`:
+  ///
+  ///  * The [FileSystemEntity] at [path] is deleted regardless of type. If
+  ///    [path] corresponds to a file or link, then that file or link is
+  ///    deleted. If [path] corresponds to a directory, then it and all
+  ///    sub-directories and files in those directories are deleted. Links
+  ///    are not followed when deleting recursively. Only the link is deleted,
+  ///    not its target. This behavior allows [delete] to be used to
+  ///    unconditionally delete any file system object.
+  ///
+  /// If this [Link] cannot be deleted, then [delete] throws a
+  /// [FileSystemException].
+  void deleteSync({bool recursive = false});
+
   /// A [Link] instance whose path is the absolute path to [this].
   ///
   /// The absolute path is computed by prefixing