From cd9cb74672682516678c38bbf678f4d611d55893 Mon Sep 17 00:00:00 2001 From: Cory Benfield Date: Wed, 15 Oct 2025 13:26:21 +0100 Subject: [PATCH] Make docs for several filesystem operations clearer. Motivation: The relationship between moveItem(at:to:) and replaceItem(at:withItemAt:) is not terribly clear. It would be good if their behaviours were more obvious. Modifications: Clean up the docs. Result: Makes the docs clearer. Resolves #3406. --- Sources/NIOFS/FileSystem.swift | 5 ++++- Sources/NIOFS/FileSystemProtocol.swift | 11 ++++++++--- Sources/_NIOFileSystem/FileSystem.swift | 5 ++++- Sources/_NIOFileSystem/FileSystemProtocol.swift | 11 ++++++++--- 4 files changed, 24 insertions(+), 8 deletions(-) diff --git a/Sources/NIOFS/FileSystem.swift b/Sources/NIOFS/FileSystem.swift index b54e6cb28b..fc03db8210 100644 --- a/Sources/NIOFS/FileSystem.swift +++ b/Sources/NIOFS/FileSystem.swift @@ -525,6 +525,10 @@ public struct FileSystem: Sendable, FileSystemProtocol { /// Replaces the item at `destinationPath` with the item at `existingPath`. /// + /// This is similar to ``moveItem(at:to:)`` except that it will replace an existing item at + /// `destinationPath` if one exists. The item at `existingPath` will be removed after the + /// operation completes successfully. + /// /// Only regular files, symbolic links and directories may replace the item at the existing /// path. The file at the destination path isn't required to exist. If it does exist it does not /// have to match the type of the file it is being replaced with. @@ -549,7 +553,6 @@ public struct FileSystem: Sendable, FileSystemProtocol { do { try await self.removeItem(at: destinationPath, strategy: .platformDefault) try await self.moveItem(at: existingPath, to: destinationPath) - try await self.removeItem(at: existingPath, strategy: .platformDefault) } catch let error as FileSystemError { throw FileSystemError( message: "Can't replace '\(destinationPath)' with '\(existingPath)'.", diff --git a/Sources/NIOFS/FileSystemProtocol.swift b/Sources/NIOFS/FileSystemProtocol.swift index 4b98032acc..d72f786100 100644 --- a/Sources/NIOFS/FileSystemProtocol.swift +++ b/Sources/NIOFS/FileSystemProtocol.swift @@ -273,10 +273,12 @@ public protocol FileSystemProtocol: Sendable { /// Moves the file or directory at the specified path to a new location. /// + /// The item at `sourcePath` will be removed after the move completes successfully. + /// /// The following error codes may be thrown: /// - ``FileSystemError/Code-swift.struct/notFound`` if the item at `sourcePath` does not exist, /// - ``FileSystemError/Code-swift.struct/invalidArgument`` if an item at `destinationPath` - /// exists prior to the copy or its parent directory does not exist. + /// exists prior to the move or its parent directory does not exist. /// /// Note that other errors may also be thrown. /// @@ -289,6 +291,10 @@ public protocol FileSystemProtocol: Sendable { /// Replaces the item at `destinationPath` with the item at `existingPath`. /// + /// This is similar to ``moveItem(at:to:)`` except that it will replace an existing item at + /// `destinationPath` if one exists. The item at `existingPath` will be removed after the + /// operation completes successfully. + /// /// The following error codes may be thrown: /// - ``FileSystemError/Code-swift.struct/notFound`` if the item at `existingPath` does /// not exist, @@ -298,8 +304,7 @@ public protocol FileSystemProtocol: Sendable { /// Note that other errors may also be thrown. /// /// The item at `destinationPath` is not required to exist. Note that it is possible to replace - /// a file with a directory and vice versa. After the file or directory at `destinationPath` - /// has been replaced, the item at `existingPath` will be removed. + /// a file with a directory and vice versa. /// /// - Parameters: /// - destinationPath: The path of the file or directory to replace. diff --git a/Sources/_NIOFileSystem/FileSystem.swift b/Sources/_NIOFileSystem/FileSystem.swift index 8b7df2bb1b..0dc29558a2 100644 --- a/Sources/_NIOFileSystem/FileSystem.swift +++ b/Sources/_NIOFileSystem/FileSystem.swift @@ -525,6 +525,10 @@ public struct FileSystem: Sendable, FileSystemProtocol { /// Replaces the item at `destinationPath` with the item at `existingPath`. /// + /// This is similar to ``moveItem(at:to:)`` except that it will replace an existing item at + /// `destinationPath` if one exists. The item at `existingPath` will be removed after the + /// operation completes successfully. + /// /// Only regular files, symbolic links and directories may replace the item at the existing /// path. The file at the destination path isn't required to exist. If it does exist it does not /// have to match the type of the file it is being replaced with. @@ -549,7 +553,6 @@ public struct FileSystem: Sendable, FileSystemProtocol { do { try await self.removeItem(at: destinationPath, strategy: .platformDefault) try await self.moveItem(at: existingPath, to: destinationPath) - try await self.removeItem(at: existingPath, strategy: .platformDefault) } catch let error as FileSystemError { throw FileSystemError( message: "Can't replace '\(destinationPath)' with '\(existingPath)'.", diff --git a/Sources/_NIOFileSystem/FileSystemProtocol.swift b/Sources/_NIOFileSystem/FileSystemProtocol.swift index 2c7844e038..cd49cada5e 100644 --- a/Sources/_NIOFileSystem/FileSystemProtocol.swift +++ b/Sources/_NIOFileSystem/FileSystemProtocol.swift @@ -273,10 +273,12 @@ public protocol FileSystemProtocol: Sendable { /// Moves the file or directory at the specified path to a new location. /// + /// The item at `sourcePath` will be removed after the move completes successfully. + /// /// The following error codes may be thrown: /// - ``FileSystemError/Code-swift.struct/notFound`` if the item at `sourcePath` does not exist, /// - ``FileSystemError/Code-swift.struct/invalidArgument`` if an item at `destinationPath` - /// exists prior to the copy or its parent directory does not exist. + /// exists prior to the move or its parent directory does not exist. /// /// Note that other errors may also be thrown. /// @@ -289,6 +291,10 @@ public protocol FileSystemProtocol: Sendable { /// Replaces the item at `destinationPath` with the item at `existingPath`. /// + /// This is similar to ``moveItem(at:to:)`` except that it will replace an existing item at + /// `destinationPath` if one exists. The item at `existingPath` will be removed after the + /// operation completes successfully. + /// /// The following error codes may be thrown: /// - ``FileSystemError/Code-swift.struct/notFound`` if the item at `existingPath` does /// not exist, @@ -298,8 +304,7 @@ public protocol FileSystemProtocol: Sendable { /// Note that other errors may also be thrown. /// /// The item at `destinationPath` is not required to exist. Note that it is possible to replace - /// a file with a directory and vice versa. After the file or directory at `destinationPath` - /// has been replaced, the item at `existingPath` will be removed. + /// a file with a directory and vice versa. /// /// - Parameters: /// - destinationPath: The path of the file or directory to replace.