Skip to content

Make docs for several filesystem operations clearer. #3409

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+24 −8
Open

Make docs for several filesystem operations clearer. #3409

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion Sources/NIOFS/FileSystem.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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)'.",
Expand Down
11 changes: 8 additions & 3 deletions Sources/NIOFS/FileSystemProtocol.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
///
Expand All @@ -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,
Expand All @@ -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.
Expand Down
5 changes: 4 additions & 1 deletion Sources/_NIOFileSystem/FileSystem.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this intentional? PR description says it's just updating docs..

} catch let error as FileSystemError {
throw FileSystemError(
message: "Can't replace '\(destinationPath)' with '\(existingPath)'.",
Expand Down
11 changes: 8 additions & 3 deletions Sources/_NIOFileSystem/FileSystemProtocol.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
///
Expand All @@ -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,
Expand All @@ -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.
Expand Down
Loading